A.C.E. 2/ACE CD 2.iso/FILES/DOCS/AMOSDOC.LHA/AmosPart2.doc

Text File | 1994-11-27 | 131.9 KB | 3,768 lines

5: STRING FUNCTIONS

        =LEFT$= (return the leftmost characters of a string)

d$=LEFT$(s$,n)

This instruction works like in nearly any Basic language (for example,
AmigaBasic). Example:

        B$="Hello! This is Ronnie!"
        L$=Left$(B$,9)
        Print L$
( result: Hello! Th )

         =RIGHT$= (return the rightmost character of a string)

d$=RIGHT$(s$,n)

Same as the LEFT$ -instruction, but takes the rightmost characters.

        Print Right$("AMOS Basic",5)
( result: Basic )

      =MID$= (return a string of characters from within a string)

d$=MID$(s$,p,n)
MID$(d$,p,n)=s$

The MID$ function returns the middle section of the string held in s$.
p denotes the offset of characters to the start of this substring, and
n holds the number of characters to be fetched. If a value of "n" is
not specified in the instruction then the characters will be read right
up to the end of your string. Example:

        Print Mid$("AMOS Basic",6)
( result: Basic )

There is also a MID$ instruction:

        MID$(d$,p,n)=s$

This version of MID$ loads "n" characters into d$ starting from
position p+1 in s$. If a value of n is not specified directly then
characters will be replaced up to the end of the source string s$. This
kind of instruction is also possible when using LEFT$ and RIGHT$.
Here's an example:

        A$="AMOS *****"
        Mid$(A$,5)="Magic"
        Print A$
( result: AMOS Magic )

                 =INSTR (search for occurrences of a
                     string within another string)

f=INSTR(d$,s$ [,p])

INSTR allows you to search for all occurrences of one string inside
another. It is often used in adventure games to split a complete line
of text into its individual commands. There are two possible formats of
the INSTR function.

f=INSTR(d$,s$)

This searches for the first occurrence of s$ in d$. If the string is
found then its position will be returned directly, otherwise the result
will be set to zero. Examples:

        Print Instr("AMOS BASIC","AMOS")
( result: 1 )
        Print Instr("AMOS BASIC","S")
( result: 4 )
        Print Instr("AMOS BASIC","AMIGA")
( result: 0 )

        Do
          Input "String to be searched";D$
          Input "String to be found";S$
          X=Instr(D$,S$)
          If X=0 Then Print S$;" Not found"
          If X<>0 Then Print S$;" Found at position ";X
        Loop

Normally the search will commence from the first character in your text
string (d$). The secont version of INSTR lets you test a specific
section in the string at a time.

  p is now the position of the beginning of your search. All characters
are numbered from the left to right starting from zero. Therefore p
ranges from 0 to LEN(s$). Example:

        Print Instr("AMOS BASIC","S",5)
( result: 8)

          =UPPER$ (convert a string of text to upper case)

s$=UPPER$(n$)

This function converts the string in n$ into upper case (capitals) and
places the result into s$. Example:

        Print Upper$("AmOs BaSic")
( result: AMOS BASIC )

               =LOWER$ (convert a string to lower case)

s$=LOWER$(n$)

LOWER$ translates all the characters in n$ into lower case. This is
especially useful in adventure games, as you can convert all the user's
input into a standard format which is much easier to interpret.
Example:

        Input "Continue (Yes/No)";ANSWER$
        ANSWER$=Lower$(ANSWER$) : If ANSWER$="no" Then Edit
        Print "Continuing with your prog..."

                       =FLIP$ (invert a string)

f$=FLIP$(n$)

FLIP$ simply reverses the order of the characters held in n$.

                     =SPACE$ (space out a string)

s$=SPACE$(n)

Generates a string of n spaces and places them into s$. Example:

        Print "Twenty" ; Space$(20); "spaces"

                 =STRING$ (create a string full of a$)

s$=STRING$(a$,n)

STRING$ returns a string with n copies of the first character in a$:

        Print String$("The cat sat on the mat",10)
( result: TTTTTTTTTT )

                    =CHR$ (return Ascii character)

s$=CHR$(n)

Creates a string containing a single character with Ascii code n.

                 =ASC (get Ascii code of a character)

c=ASC(a$)

ASC supplies you with the internal Ascii code of the first character in
the string a$:

        Print Asc("B")
( result: 66 )

         =LEN (returns the number of characters stored in a$)

This way you can get the length of a string:

        Print Len("12345678")
( result: 8 )

                   =VAL (convert a string to number)

v=VAL(x$)
v#=VAL(x$)

VAL converts a list of decimal digits stored in x$ into a number. If
this process fails for some reason, a value of zero will be returned
instead. Example:

        X=Val("1234):Print X
( result: 1234 )

                 =STR$ (convert a number to a string)

s$=STR$(n)

STR$ converts an integer variable into a string. This can be very
useful because some functions, such as CENTRE, do not allow you to
enter numbers as a parameter. Example:

        Centre "Memory left is "+Str$(Chip Free)+" Bytes."

Do not confuse STR$ with STRING$.

Array options

                 SORT (sort all elements in an array)

SORT a(0)
SORT a#(0)         The SORT instruction arranges the contents of any
SORT a$(0)         array into ascending order. This array can contain
                   either strings, integers, or floating point numbers.
The a$(0) parameter specifies the starting point of your table. It must
always be set to the first item in the array (item number 0). Example:

        Dim A(25)
        P=0
        Repeat
          Input "Input a number (0 to stop)";A(P)
          Inc P
        Until A(P-1)=0 Or P>25
        Sort A(0)
        For I=0 to P-1
          Print A(I)
        Next

                        MATCH (search an array)

r=MATCH(t(0),s)
r=MATCH(t#(0),s#)     MATCH searches through a sorted array for the
r=MATCH(t$(0),s$)     value s. If this is succesfully found then r
                      will be negative. Taking the absolute value of
this figure will provide you with the item which came closest to your
original search parameter.

  Note that only arrays with a single dimension can be checked in this
way. You'll also need to sort the array with SORT before calling this
function. Example:

        Read N
        Dim D$(N)
        For I=1 to N
          Read D$(I)
        Next I
        Sort D$(0)
        Do
          Input A$
          If A$="L"
            For I=1 to N:Print D$(I):Next I
          Else
            POS=Match(D$(0),A$)
            If POS>0 Then Print "Found",D$(POS);" In Record ";POS
            If POS<0 And Abs(POS)<=N Then Print A$,"Not Found. Closest
                                                     To ",D$(Abs(POS))
            If POS<0 And Abs(POS)>N Then Print A$, "Not Found. Closest
                                                            To ";D$(N)
          Endif
        Loop
        Data 10,"Adams","Asimov","Shaw","Heinlien","Zelazny","Foster"
        Data "Niven","Harrison","Pratchet","Dickson"

Note that MATCH could be used in conjunction with the INSTR function to
provide a powerful parser routine. This might be used to interpret the
instructions you entered in an adventure game.

6:GRAPHICS
AMOS Basic provides you with everything you need to generate some
amazing graphics. There's a comprehensive set of commands for drawing
rectangles, circles and polygons. As you would expect from the Amiga,
all operations are performed practically instantaneously. But even here
AMOS Basic has a trick or two up its sleeve.

  The AMOS graphical functions work equally well in all the Amiga's
graphics modes INCLUDING hold and modify mode (HAM). It's therefore
possible to create breathtaking HAM pictures directly within AMOS
Basic!

  Furthermore, you're not just limited to the visible screen. If you've
created an extra large playing area, you'll be able to access every
part of your display using the standard drawing routines. So it's easy
to generate the scrolling backgrounds required by arcade games such as
Defender.

Colours
The Amiga allows you to display up to 64 colours on the screen at a
time. These colours can be selected using the INK,COLOUR and PALETTE
commands.

              INK (set colour used by drawing operations)

INK col[,paper][,border]

"col" specifies the colour which is to be used for all subsequent
drawing operations. The colour of every point on the screen is taken
from one of 32 different colour registers. These registers can be
individually set with a colour value chosen from a palette of 4096
colours.

  Although the Amiga only provides you with 32 actual color registers,
AMOS lets you use colour numbers ranging from 0 to 63. This allows you
to make full use of the colours available from the Half-Bright and HAM
modes respectively. A detailed explanation of these modes can be found
in the Screens chapter.

  The "paper" colour sets the background colour fill patterns generated
by the SET PATTERN command.

  The "border" colour selects an outline colour for your bars and
polygons. This option can be activated using the SET PAINT command like
so:

        Set pattern 0 : Set paint 1
        Repeat
          C=Rnd(16):Ink 16-C,0,C
          X=Rnd(320)-20:Y=Rnd(200)-20:S=Rnd(100)+10
          Bar X,Y to X+S,Y+S
        Until Mouse Key

Note that any of the parameters col, paper and border, may be omitted.
Simply include "empty" commas at the appropriate places in the
instruction. For example:

        Ink ,,5 : Rem  Just sets the border colour

                  COLOUR (assign a colour to an index)

COLOUR index,$RGB

The COLOUR instruction allows to assign a colour to each of the Amiga's
32 colour registers.

  "Index" is the number of the colour you wish to change, and can range
from 0-31. As you may know, any colour can be created by mixing
specific amounts of the primary colours Red, Green and Blue. The shade
of your colour is completely determined by the relative intensities of
the three components

  The expression $RGB consists of three digits from 0 to F. Each
component sets the strength of one of the primary colours, Red (R),
Green (G) or Blue (B). The size of the components is directly
proportional to the brightness of the associated colour. So the higher
values, the brighter the eventual colour.

        Hex Digit   0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
        Decimal     0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15

HAM and Extra Half-Bright modes use these indices slighty differently.
See Chapter 9 for more details.

                 =COLOUR (read the colour assignment)

c=COLOUR(index)

The COLOUR function takes an index number from 0 to 31, and returns the
coour value which has been previously assigned to it.
  "Index" is simply the colour number whose shade you wish to
determine. You can use this function to produce a list of the current
colour settings of your Amiga like so:

        For C=0 To 15
          Print Hex$(Colour(C),3)
        Next C

               PALETTE (set the current screen colours)

PALETTE list of colours

The PALETTE instruction is really just a rather more powerful version
of COLOUR. Instead of loading the colour values one at a time, the
PALETTE command allows you to install a whole new palette of colours in
a single statement.

        However you don't have to set all the colours in the palette at
once. Any combination of colours can be loaded individually ;

        PALETTE $100,$200,$300 : Rem Sets just three colours

You can also change selected colours in the middle of your list ;

        PALETTE $200,,$400 : Rem Change colours 0 and 2

It's important to realise that only the colours in the palette which
are specifically set by this command will actually be changed. All
other colours will retain their original values. Here are some
examples:

        Palette 0,$F00,$0F0
        Palette 0,$770
        Palette 0,,$66
        Palette 0,$1,$2,$3,$4,$5,$6,$7,$8,$9,$A,$B,$C,$D,$E,$F

At the start of your program the colour palette is automatically loaded
using a list of default color values. These settings can be adjusted
using a simple option from the AMOS configuration program.

  This command can also be used to set the colours used by the
Half-Bright and HAM modes. These extend the existing colour palette to
generate dozends of extra colours on the screen. See chapter 10...

Line drawing commands

                 GR LOCATE (position graphics cursor)

GR Locate x,y

This sets the position of the graphics cursor to screen coordinates
x,y. The graphics cursor is used as the default starting point for most
drawing operations. So if you omit the coordinates from commands such
as PLOT or CIRCLE, the objects will be drawn at the current cursor
position. For example:

        Gr Locate 10,10 : Plot ,
        Gr Locate 100,100 : Circle ,,100



               =XGR (return x coordinate of gfx cursor)
               =YGR (return y coordinate of gfx cursor)

x=XGR
y=YGR

These functions return the present coordinates of the graphics cursor:

        Circle 10,100,100
        Print Xgr,Ygr


                      PLOT (plot a single point)

PLOT x,y [,c]

The PLOT command is the simplest drawing function provided by AMOS
Basic. It plots a point at coordinates x,y using colour c. The new ink
colour will now be used in all subsequent drawing operations.

  If the colour "c" is omitted from this instruction, the point will be
plotted in the current colour. For example:

        Curs Off: Flash Off : Randomize Timer
        Do
          Plot Rnd(319),Rnd(199),Rnd(15)
        Loop

It's also possible to omit the X or Y coordinates from this
instruction. The point will be plotted at the gfx cursor position.

        Plot 100,100,4
        Plot ,150
        Cls : Plot ,


                   POINT (get the colour of a point)

c=POINT(x,y)

POINT returns the colour index of a point at coordinates x,y ;

        Plot 100,100
        Print "The colour at 100,100 is ";Point(100,100)

                          DRAW (draw a line)6

DRAW is another very Basic instruction. Its action to draw a simple
straight line on the Amiga's screen.

        DRAW x1,y1 TO x2,y2

Draws a line between the coordinates x1,y1 and x2,y2

        DRAW TO x3,y3

Draw a line from the current gfx crsr position to x3,y3. Example:

        Colour 4,$707:Ink 4
        Draw 0,50 To 200,50
        Draw To 100,100
        Draw To 0,50

                     BOX (draw a hollow retangle)

BOX x1,y1 TO x2,y2

The BOX command draws a hollow retangular box on the screen. x1,y1 are
the coordinates of the top left corner of the box, and x2,y2 are the
coordinates of the point diagonally opposite.


                   POLYLINE (multiple line drawing)

POLYLINE is very similar to DRAW except that it draws several lines at
a time. It's capable of generating complex hollow polygons in just a
single statement.

        POLYLINE x1,y1 TO x2,y2 TO x3,y3


                     CIRCLE (draw a hollow circle)

CIRCLE x,y,r

The Circle command draws a hollow circle with radius r and centre x,y.

As normal, if the coordinates are omitted from this command, the circle
will be drawn from the current cursor position;

        Plot 100,100 : Circle ,,50


                    ELLIPSE (draw a hollow ellipse)

ELLIPSE x,y,r1,r2

The ELLIPSE instruction draws a hollow ellipse at coordinates x,y. The
horizontal radius is r1. It corresponds to exactly half the width of
the ellipse. r2 is the vertical radius and is used to set the height of
the ellipse. The total height of the ellipse is r*2

Line types
AMOS Basic allows you to draw your lines using a vast range of possible
line styles.

                    SET LINE (set the line styles)

SET LINE mask

The SET LINE command sets the style of all lines which are subsequently
drawn using the DRAW, BOX and POLYLINE commands.

  "Mask" is a 16-bit binary number which describes the precise
appearance of the line. Any points in the line which are to be
displayed in the current ink colour are represented by a one, and any
points which are to be set to the background colour are indicated by a
zero. So a normal line is denoted by the binary number
%1111111111111111 and will be displayed as _______. Similarly, a dotted
line like _ _ _ _ will be produced by a mask of %1111000011110000.

  By setting the line mask to values between 0 and 65535, it is
possible to generate a great variety of different line types ;

        Set Line $F0F0
        Box 50,100 To 150,150

This line style as no effect on shapes drawn with CIRCLE or ELLIPSE.

Filled shapes

                         PAINT (contour fill)

PAINT x,y,mode

The PAINT command allows you to fill any region on the screen with a
solid block of colour. Additionally you can select a fill pattern for
your shapes using the SET PATTERN command.

  x,y are the coordinates of a point inside the area to be filled.
"Mode" can be set to either 0 or 1. A value of 0 terminates the filling
operation at the first pixel found with the current border colour. A
mode of 1 halts the filling operation at any colour which is different
from the existing ink colour.

See EXAMPLE 6.1  in the MANUAL folder for a demonstration.

                     BAR (draw a filled rectangle)

BAR x1,y1 TO x2,y2

Draws a filled bar from x1,y1 -the coordinates of the top left corner
of the bar- to x2,y2 -the opposite corner coordinates.

                    POLYGON (draw a filled polygon)

POLYGON x1, TO x2,y2 TO x3,y3 ...
POLYGON TO x1,y1 TO x2,y2 ...

POLYGON generates a filled polygon in the current ink colour It's
basically just a solid version of the standard POLYLINE command.
There's no real limit to the number of coordnate pairs you may use,
other than the maximum line length permitted by AMOS Basic (255 chars).

Fill types
In AMOS Basic you're not just restricted to filling your shapes with a
solid block of colour. There are dozens of fill patterns to choose
from, and you can even load your own patterns directly from the sprite
bank.

                   SET PATTERN (select fill pattern)

SET PATTERN pattern

This command allows you to select a fill pattern for use by your
drawing operations. There are three possibilities

        Pattern=0

This is the default, and fills your shapes with a solid block of the
current INK colour.

        Pattern>0

If the pattern number is >0, AMOS Basic selects on of 34 built-in fill
styles. These are found in the MOUSE.ABK file on your start-up disc,
and can be edited using the AMOS Basic sprite definer. Note that the
first three images in this files are required by the mouse cursor (see
CHANGE MOUSE). The fill patterns are stored in the images from four
onwards.

        Pattern<0

This is the most powerful option of all. "Pattern" now refers to a
sprite image in bank one. The image is number calculated using the
formula:  SPRITE IMAGE = PATTERN * (-1)

The selected image will be automatically truncated before use,
according to the following rules

 * The width of the image will be clipped to sixteen pixels
 * The height will be rounded to the nearest power of two, ie 1,2..,64

Depending on the type of your image, the pattern will be drawn in one
of two separate ways. Two-colour images are drawn in "monochrome". The
actual colours in your image are completely discarded, and the pattern
is drawn using the current ink and paper colours.

  It's also possible to produce multi-coloured fill patterns. In this
case the foreground colours of your image and merged with the current
ink colour using a logical AND. Similarly the paper colours of your
pattern is OR'ed with the sprite background (colour zero). If you wish
to use your original sprite colours, you'll need to set the ink and
background colours like so:

        Ink 31,0

Don't forget to load your sprite palette from the sprite bank with
GET SPRITE PALETTE before using these instructions, otherwise the
display is likely to look rather messy. Examples of this instruction
can be found in EXAMPLE 6.2  in the MANUAL folder.

                 SET PAINT (set / reset outline mode)

SET PAINT n

Toggles the outline drawn by the POLYGON or BAR instructions. As a
default this mode is set to OFF.

  If n=1 then outline mode will be activated.

Writing styes

                   GR WRITING (ghange writing mode)

GR WRITING bitpattern

Whenever you draw some graphics on the screen, you naturally assume
that anything underneath it will be overwriteen. The GR WRITING command
allows you to choose from a range of four alternative drawing modes.
These can used to generate dozens of intriguing effects.

  "Bitpattern" holds a sequence of binary bits which specify which
graphics mode you wish to use. Here's a list of the various
possibilities along with a brief explanation of their effects:

JAM1 mode (Bit 0=0)
                    JAM1 only draws the parts of your graphics which
are set to the current INK colour. Any sections drawn in the paper
colour are totally omitted. This is particularly useful with with the
TEXT command as it allows you to merge your text directly over an
existing screen background. For example:

        Ink 2,5:Text 140,80,"Normal Text":Gr Writing 0:
                                     Text 140,71,"JAM1"

JAM2 mode (Bit 0=1)
                    This is the default condition. Any existing
graphics on the screen will be completely replaced by your new image.


XOR mode (Bit 1=1)
                    XOR combines your new graphics with those already
on the screen using a logical operation known as eXclusive OR. The net
result is to change the colour of the areas of a drawing which overlap
an existing picture.

  One interesting side effect of XOR mode is that you can erase any
object from the screen by simply setting XOR mode and drawing your
object again at exactly the same position. EXAMPLE 6.3  contains a
simple demonstration of this technique and produces a neat rubber and
banding effect.

INVERSEVID (Bit 2=1)
                     This reverses the image before it is drawn. So any
sections of your image drawn in the ink colour will be replaced by the
current paper colour and vice-versa. INVERSEVID mode is often used to
produce inverted text.

  Since these modes are set using a bitpattern, it's possible to
combine several mode together.

        Gr Writing 4+1 : Rem set JAM2 and INVERSEVID
        Gr Writing 7   : Rem chooses JAM2,INVERSEVID and XOR
        Ink 2,5 : Text 140,80,"Accession & Image rulez!"

NOTE: This command only affects drawing operations such as CIRCLE, BOX
and graphical text (TEXT). The drawing mode used by normal text
commands like PRINT and CENTRE is set using a separate WRITING command.
See also AUTOBACK.

          CLIP (restrict all gfx to a section of the screen)

CLIP [x1,y1 TO x2,y2]

The CLIP instruction limits all drawing operations to a rectangular
region of the screen specified by the coordinates x1,y1 to x2,y2.

  x1,y1 represent the coordinates of the top left hand corner of the
rectangle, and x2,y2 hold the coordinates of the bottom right corner.

  Note that it's perfectly acceptable to use coordinates outside the
normal screen boundaries. All the clipping operations will work as
expected, even if only a section of the clipping rectangle is actually
visible.

  As you can see, only the parts of the circle which lie within the
clipping rectangle have been drawn on the screen. The clipping zone can
be restored to the normal screen area. by omitting all the coordinates
from this instruction.

  See EXAMPLE 6.4  in the MANUAL folder.

Advanced techniques

                  SET TEMPRAS (set temporary raster)

SET TEMPRAS [address,size]

This instruction allows experienced Amiga programmers to fine tune the
amount of memory used by various graphics operations. WARNING:
improper use of this instruction can crash your Amiga copletely!

  Whenever an AMOS program performs a fill command, a special memory
area is reserved to hold the fill pattern. This memory is automatically
returned to the system after the instruction has been terminated. The
size of the memory buffer is equivalent to a single bit plane in the
current screen mode. So the default screen takes up to a total of 8k.

  The size and location of the graphics buffer can be changed at any
time using the SET TEMPRAS instruction.

  "Size" is the number of bytes you wish to reserve for your buffer
area. It ranges between 256 and 65536.

  The amount of memory required for a particular object can be
calculated in the following way:

        - Enclose the object to be drawn with a rectangular box
        - The area required will given by: Size=Width/8 * Height.

If you are intending to use the PAINT command, you should take care to
ensure that your figure is *closed*, otherwise more memory will be
neede and the system may crash.

  "Buffer" can be either an addess or a memory bank. The memory you
reserve for this buffer should always be CHIP ram. Since the buffer
area is now allocated once and for all at the start of your program,
there's no need to continually reserve and restore the memory buffer.
This can speed up the execution of your programs by up to 5 %.

  You can restore the buffer area to its original value by calling the
SET TEMPRAS command with no parameters.

  See the EXAMPLE 6.5  in the MANUAL folder.

7:CONTROL STRUCTURES

                   GOTO (jump to a new line number)

The action of GOTO is to transfer the control of the program one place
to another. There are three forms of the GOTO command allowes in AMOS;

        GOTO label

"label" is an optional place marker at the side of a line. Label names
are defined using the ":" colon character like so:

        label:

The label name can consist of any string of alphanumeric characters you
like, including "-". It's constructed using the same rules which apply
for variables and procedure names.

        GOTO line number

Any AMOS Basic line can be optionally preceded with a number. These
line numbers are included solely for compatibility purposes with other
versions of Basic (such as STOS for the Atari ST). It's better to rely
on labels instead, as these are much easier to read and remember.

        GOTO variable

Variable can be any allowable AMOS Basic expression. This expression
may be either a normal ingerer or a string. Integers run a line number
for your GOTO, whereas strings hold the name of a label.

  Technically speaking, this construction is known as a computed goto.
It's generally growned upon by serious programmers, but it can be
incredibly useful at times. Examples:

        ROOM=3
        BEGIN:
        Goto "ROOM"+Str$(ROOM)-" "
        End
        ROOM3:
        Print "Room three!"
        Goto BEGIN

                     GOSUB (jump to a subroutine)

GOSUB is another outmoded instruction, and provides you with the useful
ability to split a program into smaller, more manageable chunks, known
as subroutines. Nowadays, GOSUB has been almost entirely supplanted by
AMOS Basic's procedure system. However, GOSUB does form a useful
half-way house when you're converting programs from another version of
Basic such as STOS.

  As with GOTO, there are three different forms of the GOSUB
instruction.

        GOSUB n         Jump to the subroutine at line n

        GOSUB name      Jump to an AMOS label

        GOSUB exp       Jump to a label or line which results from the
                        expression in "exp".

        Example:

        For I=1 To 10
          Gosub TEST
        Next I
        Direct
        TEST:
        Print "This is an example of GOSUB":Print "I equals ";I
        Return: Rem Exit from subroutine TEST and return to main prg.

It's good practice to always plave your subroutines at the end of your
main program as this makes them easier to pick out from your program
listings. You should also add a statement like EDIT or DIRECT to end of
your main program, as otherwise AMOS may attempt to execute your GOSUBs
after the program has finished, generating an error message.

                   RETURN (return from a subroutine)

RETURN

RETURN exits from a subroutine which was previously entered using
GOSUB. It immediately jumps back to the next Basic instruction after
the original GOSUB.

  Note that a single GOSUB statement can contain several RETURN
commands. So you can exit from any number of different points in your
routine depending on the situation.

              POP (remove the RETURN info after a GOSUB)

POP

Normally it's illegal to exit from a GOSUB statement using a standard
GOTO. This can occassionally be inconvenient, especially if an error
occurs, which makes in unacceptable to return to your program from the
precice point you left it.

  The POP instruction removes the return address generated by your
GOSUB, and allows you to leave the subroutine in any way you like,
without first having to execute the final RETURN statement. Example:

        Do
          Gosub TEST
        Loop
        BYE:
        Print "Popped Out"
        Direct :
        TEST:
        Print "Hi there!"
        If Mouse Key Then Pop : Goto BYE
        Return

        IF...THEN...[ELSE] (coose between alternative actions)

The IF...THEN instruction allows you to make simple decisions within a
Basic program. The format is:

IF conditions THEN statements 1 [ELSE statements 2]

"conditions" can be any list of tests including AND and OR. Statements
1 and Statements 2 must be a list of AMOS Basic instructions. If you
want to jump to a line number or a label, you'll have to include a
separate GOTO command like so:

        If test Then Goto Label : This is fine.
                     ----
If you forget about this, and leave the "Goto", you'll get an error
message "procedure not defined".

        If test Then Label : Rem THIS CALLS A *PROCEDURE*

The scope of this IF...THEN statement is limited to just a single line
of your Basic program. It has now been superceded by the much more
powerful IF...ELSE...ENDIF command.

                 IF...[ELSE]...ENDIF (structured test)

Although the original form of IF...THEN is undoubtedly useful, it's
rather old fashioned when compared with the facilities found in a
really modern version of Basic such as AMOS. This allows you to execute
whole lists of instructions depending on the outcome of a single test.

        IF tests=TRUE
          <List of statements 1>
               "       "
        ELSE
          <List of statements 2>
               "       "
        ENDIF

Note: it's illegal to use a normal IF...THEN inside a structured test!
These should be replaced by their equivalent IF...ENDIF instruction ;

        If test Then Goto Label Else Label2

This now becomes:

        If test : Goto Label : Else goto Label2 : Endif

or:

        If test
          Goto Label
        Endif

Here is an example of the IF...ENDIF statement in action:

        Input "Enter values for a,b and c";A,B,C
        If A=B
          Print "Equal"
        ELSE
          Print "Different";
          If A<>B and A<>C
            Print ", and C is not the same too!"
          Endif
        End if

Each IF statement in your program MUST be paired with a single ENDIF
command as this informs AMOS Basic precisely which group of
instructions are to be executed inside your test.

Note that "THEN" is not used by this form of the instruction at all.
This may take a little getting used to if you are already experienced
with one of the other versions of Basic for the Commodore Amiga.

                FOR...NEXT (repeat a section of a code
                      a specific number of times)

FOR index=first TO last [STEP inc]
<list of instructions>
         "
NEXT [index]

"Index" holds a counter which will be incremented after each and every
loop. At the start of the loop, this counter will be loaded with the
result of the expression "first". The instructions between FOR and the
NEXT are now performed until the NEXT is reached.

  "inc" is a value which will be added to the counter after each loop
by the NEXT instruction. If this is omitted, the increment will be
automatically set to 1.

  Note that if "inc" is negative, the loop will be halted when the
counter is less than the value in "first". So the entire loop will be
performed in reverse.

  Once inside loop, "index" can be read from your program just like a
normal variable. But you are *NOT* allowed to change its value in any
way as this will generate an error message.

  Each FOR statement in your program MUST be matched by a single NEXT
instruction. You can't use the shorthand forms found in other Basics
like NEXT R1,R1. Here are a couple of examples of these loops:

        For I=32 to 255 : Print Chr$(I);:Next I

        For R1=20 to 100 Step 20
          For R2=20 to 100 Step 20
            For A=0 To 3
              Ink A
              Ellipse 160,100,R1,R2
            Next A
          Next R2
        Next R1

                   WHILE...WEND (repeat a section of
                    code while a condition is true)

WHILE condition
  :     :
list of statements
  :     :
WEND

"condition" can be any set of tests you like and can include the
constructions AND, OR and NOT. A check is made on each turn of the
loop. If the test returns a value of -1 (true), then the statements
between the WHILE and WEND will be executed, otherwise the loop will be
aborted and Basic will proceed to the next insturction. Type the
following example:

        Input "Type in a number";X
        Print "Counting to 11"
        While X<11
          Inc X
          Print X
        Wend
        Print "Loop terminated"

The number of times WHILE loop in this program will executed depends on
the value you input to the routine. If you enter a number larger than
10, the loop will never be executed at all. WHILE will therefore only
execute the statements if the condition is TRUE at the start of your
program.

        REPEAT...UNTIL (repeat until a condition is satisfied)

REPEAT
 :  :
list of statements
 :  :
UNTIL condition

REPEAT...UNTIL is similar to WHILE...WEND except that the test
completion is made at the end of the loop rather than the beginning.
The loop will be repeated continually until the specified condition is
FALSE. So it will always be performed at least once in your program.
Example:

        Repeat
          Print "AMOS Basic"
        Until Mouse Key<>0


                       DO...LOOP (loop forever)

DO
:  :
list of statements
:  :
LOOP

The DO...LOOP commands take a list of Basic statements and repeat them
continually. In order to exit from this loop, you'll need to use a
special EXIT or EXIT IF instruction.

The advantage of this system is that it's a structure alternative to
the GOTO loops that tend to crop up in earlier versions of Basic. Take
the following example:

        TEST:
        Input "Another game (Y/N)";AN$
        If Upper$(AN$)="N" Then Goto BYE
        GAME : Rem call play game procedure
        Goto TEST
        BYE:
        End

Now a second version using DO...LOOP

        Do
          INput "Another game (Y/N)";AN$
          Exit If Upper$(AN$)="N"
          GAME : Rem call play game procedure
        Loop
        End


                     EXIT (Exit from a DO...LOOP)

EXIT [n]
The EXIT command exits immediately from one ore more program loops
created with the FOR...NEXT, REPEAT...UNTIL, WHILE...WEND, or DO...LOOP
statements. Your AMOS program will now jump directly to the next
instruction after the current loop.

  "n" is the numver of loops you wish to leave. If it's omitted, then
only the innermost loop will be terminated.

            EXIT IF (Exit from a loop depending on a test)

EXIT IF expression[,n]

"expression" consistes of a series of tests in the standard AMOS
format. The EXIT will only be performed if the result evaluates to -1.

  The "n" parameter works the same way as using EXIT command.

           EDIT (stop running the prog and return to Editor)

EDIT
The EDIT directive stops the current program and returns to the AMOS
Basic editor. This can be very useful when you are debugging one of
your progs.

                     DIRECT (exit to direct mode)

DIRECT
Terminates your program and jumps to the direct mode immediately. You
can now examine the contents of your variables or list your programs
out to the printer.

                      END (Exit from the program)

END
This instruction exits from a program. You'll now be given the option
to return to either the editor or to direct mode.

                   ON...PROC (jump to one of several
                  procedures depending on a variable)

ON v PROC proc1, proc2, proc3, ...procN

Jumps to a named procedure depending on the contents of variable v.
Note that any procedures you use in this command CANNOT include
parameters. If you need to transfer information to this procedure, you
should place them in *global* variables instead. See PROCEDURES for a
full explanation of this technique.

  The ON...PROC command is effectively equivalent to the following:

        If v=1 Then Proc1
        If v=2 Then Proc2
          :    :
        If v=n Then ProcN

               ON...GOTO (jump to one of a list of lines
                       depending on a variable)

ON v GOTO line1, line2, line3, ...lineN

The ON GOTO instruction lets your program jump to one of a number of
lines depending on the result of an expression in v. It's equivalent to
the following lines:

        If v=1 Then Goto Line1
        If v=2 Then Goto Line2
          :     :
        If v=n Then Goto LineN

                  ON...GOSUB (GOSUB one of a list of
                       routines dependig on var)

ON var GOSUB line1, line2, line3, ...

This is identical to ON...GOTO except it uses a gosub rather than a
goto to jump the line.

        EVERY n GOSUB (call a subroutine at regural intervals)

EVERY n GOSUB label
The ON EVERY statement calls the subroutine at label at regural
intervals, without interfering with your main program.

  "n" is the length of your interval in 50ths of a second. The time
taken for your subroutine to complete must always be less than this
period, or you'll get an error.

  After a subroutine has been entered, the system will automatically
disabled. In order to call this feature continuously, you'll therefore
need to add EVERY ON command before the final RETURN statement ;

        Every 50 Gosub TEST
        Do
          Print "Main loop"
        Loop
        TEST:
        Inc I : Print "This is call number ";I
        Every On:Return

         EVERY n PROC (call a procedure at regural intervals)

EVERY n PROC name

EVERY PROC execute the required procedure automatically at regular
intervals using a powerful interrupt system.

  "n" is the delay between each successive procedure call measured in
units of a 50th of a second.

  As with the previous command, the interrupt must be reactivated
before leaving your procedure, otherwise the routine will only be
called just once. So you'll need to use EVERY ON before returning to
your main program with END PROC ;

        Every 50 Proc TEST
        Do
          Print "Main loop"
        Loop
        Procedure TEST
          Shared I
          Inc I : Print "This is call number ";I
          Every On
        End Proc

            EVERY ON/OFF (toggle automatic procedure calls)

EVERY ON/OFF
EVERY ON restarts the interrupt system used by the EVERY commands. It
should be called just before the procedure or subroutine has finished
executing.

EVERY OFF disables the calls completely. It's automatically executed at
the start of one of these procedures.

            BREAK ON/OFF (turn on/off the CTRL+C Break key)

BREAK ON/OFF

Normally you can interrupt a program and return to Basic at any time by
simply pressing CTRL+C. This function can be deactivated using the
BREAK OFF command. You can restart the Break keys using BREAK ON

Error handling

           ON ERROR GOTO (trap an error within a Basic prog)

ON ERROR GOTO label

This command allows you to detect and correct the errors inside an AMOS
Basic program, without having to return to the editor window.
Sometimes, errors can arise in a program which are impossible to
predict in advance. Take, for instance, the following routine:

        Do
          Input "Enter two numbers";A,B
          Print A;" divided by ";B;" is ";A/B
        Loop

This program works fine until you try to enter a zero for B. You can
avoid the "division by zero error" by trapping the error with an ON
ERROR GOTO instruction like so:

        ON ERROR GOTO label

Whenever an error occurs in your Basic program, AMOS will now jump
straight to "label". This will be the starting point of your own error
correction routine which can fix the error and safely return to your
main program.

  Note that error handler MUST exit using a special RESUME instruction.
You are not allowed to jump back to your program with a normal GOTO
statement.

        On Error Goto HELP
        Do
          Input "Enter two numbers";A,B
          Print A;" divided by ";B;" is ";A/B
        Loop
        HELP:
        Print : Print : Bell
        Print "I'm afraid you've attempted to divide with zero!"
        Resume Next: Rem Return back to the next instruction.

In order for this system to work, it's essential that an error does not
arise inside your error correction routine, otherwise AMOS will halt
your program ignominiously.

  The action of ON ERROR GOTO can be disabled by calling ON ERROR with
no parameters.

        On Error : Rem Kill error traps

            ON ERROR PROC (Trap an error using a procedure)

ON ERROR PROC name

Selects a procedure which will be called automatically if there's an
error in the main program. It's really just a structured version of the
ON ERROR GOTO statement.

  Although your procedure must be terminated by and END PROC in the
normal way, you'll need to return to your main program with an
additional call to RESUME. This can be placed just before the final END
PROC statement.

                RESUME (resume execution of the program
                            after an error)

There are five possible formats of this instruction:

        RESUME

Jumps back to the statement which caused the error and tries again.

        RESUME NEXT

Returns to the instruction just after the one which caused the error.

        RESUME LINE

Jumps to as specific line point in your main program. "line" can refer
to either a label or a normal line number. This may *NOT* be used to
re-enter a procedure!

  Procedures are treated slightly differently. If you want to jump to a
particular label, you have to place a special marker somewhere in the
procedure you are checking for errors. This may be accomplished using
the RESUME LABEL command. There are two separate versions.

        RESUME LABEL label

Defines the label which is to be returned after an error. This must be
called outside your error handler just after the original ON ERROR PROC
or ON ERROR GOTO statement.

        RESUME LABEL

Used inside your error handler to jump straight back to the label
you've set up with the previous command. Example:

        On Error Proc HELP
        Resume Label AFTER
        Error 12
        Print "Never Printed"
        AFTER : Print "I've returned here"
        End
        Procedure HELP
          Print "Oh Dear, I think there's an error!"
          Resume Label
        Endproc

                =ERRN (return the number of last error)

e=ERRN

If you're creating your own error handling routines using the ON ERROR
command, you'll need to be able to check precisely which error has
occurred in the main program.

  When an error occurs, ERRN is automatically loaded with its
identification number. See the Apeendix at the end of this manual for a
full list of the possible errors.

        Print ERRN

          ERROR (generate an error and return to the Editor)

ERROR n
The action of the ERROR command is to actually generate an error.
Supposing you have created a nice little error handling routine which
is able to cope with all possible disc errors. ERROR provides you with
a simple way of simulating all the various problems, without the
inconvenience of the actual error. Example:

        Error 40

Quits the program and prints out a "Label not defined" error.

        Error Errn

This uses the ERRN function to print the current error condition after
a problem in your program.

8: TEXT AND WINDOWS

Text Attributes
                       PEN (set colour of text)

PEN index
The PEN instruction sets the colour of all the text which will be
displayed in the current window. This colour can be chosen from one up
to 64 different possibilities depending on the gfx mode you're using.
Example:
          PEN 6

          =PEN$(n) (change the pen colour using ctrl chrars)

a$=PEN$(n)

PEN$ returns a special control sequence which changes the pen colour
inside a string. The new pen colour will be automatically assigned
whenever this string is subsequently printed on the screen. Example:

        C$=Pen$(2)+"White "+Pen$(6)+"Blue"
        Print C$

The string returned by PEN$ is in the format:
 Chr$(27)+"P"+Chr$(48+n)

               PAPER (set colour of the text background)

PAPER index

"index" can be a number between 0-63.

               =PAPER$(n) (return a control sequence to
                         set the paper colour)

x$=PAPER$(index)

PAPER$ returns a character string which automatically changes the
background colour when it's printed on the screen. For example:

        Pen 1: C$=Paper$(2)+"White "+Paper$(6)+"Blue"
        Print C$


                  INVERSE ON/OFF (enter inverse mode)

INVERSE ON/OFF

The INVERSE command swaps the text and the background colours.

               SHADE ON/OFF (shade all subsequent text)

SHADE ON/OFF

SHADE ON highlights your text by reducing the brightness of the
characters with a mask pattern. The shade of your text can be returned
to normal using SHADE OFF

                   UNDER ON/OFF (set underline mode)

UNDER ON/OFF

UNDER ON underlines your text when it's printed on the screen. UNDER
OFF turns off the mode.

                  WRITING (change text writing mode)

WRITING w1 [,w2]

The WRITING command allows you to change the writing mode used for all
subsequent text operations. This determines precisely how your new text
will be combined with the existing screen data.

        w1=0   REPLACE (Default)   Your new text will obliterate
                                   anything underneath it.
        w1=1   OR                  Merges the characters onto the
                                   screen with a logical OR.
        w1=2   XOR                 Chars are combined now with XOR.

        w1=3   IGNORE              Printing operations are ignored!

The secont number chooses which parts of the text will be printed on
the screen. This option can be omitted if required.

        w2=0   Normal       The text is output to the screen along with
                            the background.
        w2=1   Paper        Only the background of the text is drawn on
                            the screen.
        w2=2   Pen          Ignores the paper colour and writes the
                            text on a background of colour zero.

Do *NOT* confuse this with GR WRITING!

Cursor functions
AMOS includes a range of facilities which let you move cursor to any
part on the screen.

                     LOCATE (position the cursor)

LOCATE x,y
LOCATE x,         Locate moves the text cursor to the coordinates x,y.
LOCATE ,y         This sets the starting point for all future printing
                  operations. All screen positions are specified using
a special set of text coordinates. These are meadured in units of a
single character relative to the top left corner of the text window.
For instance the coordinates 15,10 refer to a point 10 chars down and
15 to the right.

  If you attempt to print something outside window limits an error will
be generated.

  Note that the current screen is always treated as window 0. So you
don't have to actually open a window before using one of these
functions.

                   CMOVE (relative cursor movement)

CMOVE w,h

Moves the cursor a fixed distance away from its present position. If
your cursor was at 10,10, then typing:

        CMOVE 5,-5

would move the cursor to 15,5. Like LOCATE you can omit either one of
the coordinates as required.

                 =AT (return a sequence of ctrl chars
                        to position the cursor)

x$=AT(x,y)

The AT function allows you to change the position of text directly from
inside a character string. It works by returning a string in the
format:
          Chr$(27)+"X"+Chr$(27)+"Y"+Chr$(48+Y)

Whenever this string is printed, the text cursor will be moved to the
coordinates x,y. For example:

      A$="This"+At(10,10)+"Is"+At(1,2)+"The Power Of"+At(20,20)+"AMOS!"
      Print A$

These AT commands are perfect for hi-score tables as they allow you to
position our text once and for all during your programs initialisation
phase. You can now update the score at the correct point on the screen
using a single print statement. Here's an example:

        HI_SCORE$=At(20,10)+"Hi Score "
        SCORE=10000
        Print HI_SCORE$;SCORE

Conversion functions
AMOS Basic provides you with four useful functions which readliy enable
you to convert between text and graphics coordinates.

           =XTEXT (convert an x coordinate gfx->text format)
           =YTEXT (convert an y coordinate gfx->text format)

t=XTEXT(x)
t=YTEXT(y)

These functions take normal x/y coordinates and convert them to text
coordinates relative to the current window. If the screen coordinate
lies outside this window then a negative value will be returned. See
EXAMPLE 8.1.

         =XGRAPHIC (convert an x coordinate text->gfx format)
         =YGRAPHIC (convert an y coordinate text->gfx format)

g=XGRAPHIC(x)
g=XGRAPHIC(y)

These functions are effectively the inverse of XTEXT and YTEXT in that
they take a text X (or) Y coordinate ranging from 0 to the width/height
of the current window and convert them to absolute screen coordinates.
See EXAMPLE 8.2

Cursor commands
The text cursor serves as a visible starting point of all future text
operations. It's usually displayed as a flashing horizontal bar,
although this may be changed using the SET CURS and CURS OFF commands.

  By moving the cursor on the screen, you can position your text
practically anywhere you like. Remember, all coordinate measurements
are taken using TEXT coordinates relative to the current window.

                          HOME (cursor home)

HOME

Moves the text cursor to the top left hand corner of the current window
(coordinates 0,0)

                          CDOWN (cursor down)                               93
CDOWN

Pushes the text cursor down by a single line.



                 =CDOWN$ (return a Chr$(31) character)
x$=CDOWN$

CDOWN$ is a function which returns a special control character which
automatically moves the cursor when it is printed. So Print CDOWN$ is
identical to CDOWN. CDOWN$ allows you to combine several cursor
movements in a single string. For example:

        C$="\"+Cdown$
        For A=0 to 20
          Print C$;
        Next A


                            CUP (cursor up)
CUP

Moves the text cursor up a line in the same way that CDOWN moves down.

                  =CUP$ (return a Chr$(30) character)
x$=CUP$

CUP$ returns a control string which moves the cursor up by a single
character.

                          CLEFT (cursor left)
CLEFT

Displaces the text cursor one character to the left.

              =CLEFT$ (Control string for CLEFT Chr$(29))
x$=CLEFT$

Moves the text cursor one character left. Works like =CUP$.

                         CRIGHT (cursor right)
CRIGHT

Moves cursor one place to the right.

       =CRIGHT$ (Generate a Chr$(28) control string for CRIGHT)

x$=CRIGHT$

Is the opposite of CLEFT$.

          XCURS (return the X coordinate of the text cursor)
          YCURS (return the Y coordinate of the text cursor)

x=XCURS
y=YCURS

XCURS is a variable containing the current X coordinate of the text
cursos (in text format). YCURS holds the Y coordinate of the cursor.

                   SET CURS (set text cursor shape)

SET CURS L1,L2,L3,L4,L5,L6,L7,L8

This instructoin allows you to change the shape of the cursor to
anything you like. The shape is specified by a list of bit-patterns
held in the parameters L1-L8, Each parameter determines the appearance
of the horizontal line of the cursor, numbered from top to bottom.

  Every bit represnts a single point in the current cursor line. If
it's set to 1 then the point will be drawn using colour number 3 -
otherwise it will be displayed in the current PAPER colours. Example:

        L1=%11111111
        L2=%11111110
        L3=%11111100
        L4=%11111000
        L5=%11110000
        L6=%11100000
        L7=%11000000
        L8=%10000000
        Set Curs L1,L2,L3,L4,L5,L6,L7,L8

               CURS ON/OFF (enable/disable text cursor)

CURS ON                          makes text cursor visible
CURS OFF                         hides the cursor in current window

                     MEMORIZE X/Y (save the X or Y
                    coordinates of the text cursor)
MEMORIZE X
MEMORIZE Y
               The Memorize commands store the current cursor position.

                   REMEMBER X/Y (restore the X or Y
                    coordinate of the text cursor)
REMEMBER X
REMEMBER Y
               REMEMBER positions the cursor at the coordinates saved
               by a previous call to MEMORIZE. If MEMORIZE has not been
          used then the coordinates will be set to zero. See EXAMPLE 8.3

         CLINE (clear part or all of the current cursor line)

CLINE [n]

Clears the line on which the cursor is positioned. If n is present then
"n" characters are cleared starting at the current cursor position.

          CURS PEN (choose a new colour for the text cursor)

CURS PEN n

Changes the colour of the text cursor to index number n.

Text Input/Output

          CENTRE (print a line of text centred on the screen)

CENTRE a$

Takes a string of characters in a$ and prints it in the centre of the
screen. This text is always output on the current cursor line.

        Locate 0,1
        Centre "This is a centered TITLE"

                       =TAB$ (print tabulation)

x$=TAB$

TAB$ returns a control character known as a TAB (Ascii 9). When this
character is printed the text cursor will be immediately moved several
places to the right. The size of this movement can be set using the SET
TAB kommand. As a default, the tab spacing is set to four (4).

                    SET TAB (change the tabulation)

SET TAB n

This specifies the distance the text cursor will move when TAB
character is printed.

                        REPEAT$ (repeat string)

x$=REPEAT$(a$,n)

The REPEAT$ function allows you to print out the same string of
characters several times using a single PRINT statement.

  It works by adding a sequenve of control characters into variable X$.
When this string is printed, AMOS simply repeats a$ to the screen n
times. Possible values for n range between 1 and 207. See EXAMPLE 8.4.

The format of the control string is:

        Chr$(27)+"RO"+A$+Chr$(27)+"R"+Chr$(48+n)

Advanced Text Commands

             ZONE$ (set up a zone around a piece of text)

x$=ZONE$(a$,n)

The ZONE$ function surrounds a section of text with a screen zone.
After you have defined one of these zones you can check for coillisions
between the zone and the mouse using the ZONE function. This allows you
to create powerful on-screen menus and dialogue boxes without having to
resort to any complicated programming tricks.

  a$ is a string containing the text for one the "Buttons" in your
dialogue box. This button will be activated automatically when you
print x$ to the screen.

  n specifies the number of screen zone to be defined. The max. number
of these zones depends on the value you specified with RESERVE ZONE.

  See the EXAMPLE 8.5 program in the MANUAL folder. The format of the
control string is:
                   Chr$(27)+"ZO"+A$+Chr$(27)+"R"+Chr$(48+n)

                  BORDER$ (add a border to some text)

x$=BORDER$(a$,n)

This returns a string of control characters which instructs AMOS to
draw a border aound the required text. It's commonly used in
conjunction with the ZONE$ command to produve the fancy buttons found
in dialogue boxes and alert windows.

  n is the border number ranging from 1 to 16 and a$ holds the text to
be enclosed by the border. The text in a$ will start at the current
cursor position so don't be surprised when you get strange results
printing at 0,0. To create a screen zone by a border try this:

        Print Border$(Zone$(" CLICK HERE ",1),2)

This would enclose the text with zone number 1 and border 2. The
control sequence is:
                     Chr$(27)+"EO"+A$+Chr$(27)+"R"+Chr$(48+n)

                  HSCROLL (horizontal text scrolling)

HSCROLL n

This scrolls all the text in the currently open window horizontally by
a single character position. n can take the following values:

        1 = Move current line to the left
        2 = Scrolls entire screen to the left
        3 = Move current line to the right
        4 = Move screen to the right

                       VSCROLL (vertival scroll)

VSCROLL n

Scrolls the text in the currently open window vertically.

        1 = Any text at the cursor line and below is scrolled down
        2 = Text at cursor line or below is moved up
        3 = Only text from the top of the screen to the cursor line
             is scrolled up
        4 = Text from top of the screen to the current cursor position
             is scrolled down
                                              Blank lines are inserted
                     to pad out the gap left by the scrollingoperation.

Windows
The AMOS windowing commands allow you to restrict your text and
graphics operations just a part of the current screen.

  AMOS windows can be used with the zone commands to produce effective
dialogue boxes such as file selectors and high score tables. A typical
warning box, for instance, can be easily generated with just a couple
lines of AMOS Basic.

                      WINDOPEN (create a window)

WINDOPEN n, x, y, w, h [,border [,set]]

The WINDOPEN instruction opens a window and displays it on the screen.
This window will now be used for all subsequent text operations.

  n is the number of the window to be defined. AMOS allows you to
create as many windows as you like, limited only by the amount of
available memory. As a default, window number zero is assigned to the
current screen. So don't attempt to re-open this window using WINDOPEN
or change it with WIND SIZE or WIND MOVE.

  x,y are the graphics coordinates of the top left hand corner of your
new window. Since AMOS windows are drawn using the Amiga's blitter
chip, the window area must always lie on a 16-pixel boundary. In order
to achieve this, the x coordinates are automatically rounded to the
nearest multiple of 16. Additionally, if you've included a border for
your window, the X coordinate will be incremented by a further eight.
This will ensure that the working area of your window always starts at
the correct screen boundary. There are no restrictions whatsoever on
the y coordinates.

  w,h specify the size in characters of the new window. These
dimensios must always be divisible by 2.

  "border" selects a border style for your window. There are 16
possible styles, with values ranging between 1 and 16.

  Window borders can also include up to two optional title lines. One
title is displayed along the top of the window and another may be added
at the bottom.

  AMOS windows may contain either text or graphics, just like the
intuition system. Each window can be assigned it's own individual
character set with the powerful WINDOW FONT command. There's also a
powerful WIND SAVE instuction which saves the screen area inside your
windows. Whenever you move one of these windows the contents underneath
will be automatically redrawn. For example:

        For W=1 To 3
          Windopen W,(W-1)*96,50,10,101
          Paper W+3 : Pen W+6 : Clw
          Print "Window ";W
        Next W

You can flick between these windows using the WINDOW command. Try
typing the following statements from the Direct mode:

        Window 1 : Print "AMOS"
        Window 3 : Print "in action!"
        Window 2 : Print "Basic"

The active window can always be distinguished by a flashing cursor -
through this can be turned off using the CURS OFF command if required.

                   WINDOW FONT (change window font)

WINDOW FONT n

Changes the font used by the current window to set n. n is the number
of a graphics font which has been previously installed with the GET
FONT command. This font *must* have dimensions of exactly 8x8.
Proportional fonts are not allowed.

  Since the window vborders make use of some of these characters, you
may get rather odd results when you're using standard WBench fonts.

          WIND SAVE (save the contents of the current window)

WIND SAVE

The WIND SAVE command allows you to move your windows anywhere on the
screen without corrputing your existing display.

  Once you've activated this feature, any windows you subsequently open
will automatically save the entire contents of the windows underneath.
This area will be redrawn whenever you close a window or move it to a
new position.

  It's important to note that this option saves the contents of the
current window, rather than the one you are defining with WIND OPEN.

  At the start of your program the current window will be the default
screen and will take up a massive 32k of memory. If you wished to save
the background underneath a dialogue box the most of this memory would
be completely wasted.

  The solution is to create a dummy window of the required size, and to
position it over the zone you wish to save. You can now execute a WIND
SAVE command and continue with your program as normal.

  When you subsequently call up your dialogue box the area underneath
will be saved as part of your dummy window. So it will be automatically
restored after your box has been removed.

               BORDER (change the window border of the)
                            current screen)

BORDER n,paper,pen

The BORDER command sets the border of the current window to style
number n. This border is drawn using a group of characters installed in
the default font. It is therefore possible to create your own border
styles using the font definer accessory.

  The paper and pen options allow you to freely choose the colours of
your border. Acceptable border numbers range from 1 to 16.

  Any of the parameters may be omitted from this instuction so the
following commands are legal:

        BORDER 2,,
        BORDER 2,,3

                 TITLE TOP (define the upper title for
                          the current window)

TITLE TOP t$

This instruction sets the top line of the current window to the title
string in t$. Only bordered windows may be titled in this way.

        Windopen 5,1,1,20,10
        Title Top "Window Number 5"
        Wait Key



               TITLE BOTTOM (define the lower title for
                          the current window)

TITLE BOTTOM b$

This command assigns the string b$ to the bottom title of the current
window.

                      WINDOW (change current window)

WINDOW n

WINDOW activates the window n as the current window. If the automatic
saving system has been initiated, this window be immediately redrawn
along with any of its contents. See EXAMPLE 8.6 in the Manual folder.

               =WINDON (Return the value current window)

w=WINDOW

WINDON returns the identification number of the currently active
window.

                 WIND CLOSE (close the current window)

WIND CLOSE

Deletes the current window. Use the WIND SAVE command if you want the
area that was hidden be redrawn by.

                       WIND MOVE (move a window)

WINDMOVE x,y

Windmove moves the current window to graphics coordinates x,y. As with
the original window definitions the x coordinate will be rounded to the
nearest 16-pixel boundary.

           WIND SIZE (change the size of the current window)

WIND SIZE sx,sy

This command changes the size of an AMOS window. The new sizes, sx and
sy, are specified in units of a single character. Sx must be divisible
by two. See EXAMPLE 8.7.

  If you've previously called the WIND SAVE command, the original
contents of your window will be redrawn by this instruction. If the new
window is smaller than the original one, any parts of the image which
lie outside will be lost. Alternatively, if you've expanded your
window, the area around your saved region will be filled with the
current paper colour. Also note that after a WIND SIZE command the text
cursor is always reset to coordinates 0,0.

                    CLW (clear the current window)

CLW

Erases the contents of the current window and fills it with the current
PAPER colour.

Slider bars
AMOS incorporates three insturctions which allow you to display a
standard slider bar on the screen. These sliders cannot be manipulated
directly with the mouse. In order to create a working slider bar,
you'll need to write a small Basic routine to perform this operate in
your main program. Due to the sheer power of the AMOS system, this is
extremely easy to accomplish, and the results can be extremely
impressive, as can be seen from EXAMPLE 8.8.

                  HSLIDER (draw a horizontal slider)

HSLIDER x1,y1 OT x2,y2,total,pos,size

Draws a horizontal slider bar from x1,y1 to x2,y2. "total" is the
number of individual units which the slider will be divided into. Each
unit represents a single item in the object you are controlling with
the slider. TSo in the editor window, "total" would be set to the
number of lines in the current program. The size of each unit is
calculated from the following formula:

        (X2-X1)/Total

"pos" is the position of the slider box from the start of the slider,
measured in the units you specified using "total". "size" is the length
of the slider box in the previous units. See EXAMPLE 8.9.

                   VSLIDER (draw a vertical slider)

VSLIDER x1,y1 TO x2,y2,total,pos,size

VSLIDER is almost identical to the previous HSLIDER insturction. It
displays a simple slider from x1,y1 to x2,y2. See EXAMPLE 8.10.

                  SET SLIDER (sets the fill patterns
                           used in a slider)

SET SLIDER b1,b2,b3,pb,s1,s2,s3,ps

Although this command looks incredibly complicated, it's actually
rather simple. SET SLIDER enters the colours and patterns to be used in
the slider bars created with the H/VSLIDER commands.

  "b1,b2,b3" set the ink, paper and outline colours for the background
of the box. "pb" chooses the fill pattern to be used for these regions.

  "s1,s2,s3" input the colours of the slider box, and "sp" selects the
pattern it is to be filled with.

  "bp" and "sp" can be any fill patterns you wish. As usual, negative
value refer to a sprite image from the current sprite bank. This allows
you to create amazing colorful slider boxes.

Fonts
There are two different types of fonts available in AMOS - text fonts
and graphic fonts. The text fonts are those used by the PRINT and
WINDOW commands. Text fonts are known as character sets and each AMOS
Basic window can have its own individual set. The graphic fonts are
much more flexible and offer a wider range of styles:

Graphic text
Your Amiga computer is capable of displaying an impressive variety of
different text styles. The original WorkBench disc was supplied with
eight attractive fonts in a range of sizes, and many more of these
fonts are freely available from the public domain. If you've upgraded
to WorkBench 1.3, you'll also be able to design your own fonts using
the FED program on the Extras disc.

  AMOS provides you with total support for these fonts. Text can be
printed in any of the available typefaces at any point on the screen.

  AMOS fonts can be used to add spice to even the most Basic games.
These are invaluable for producing the loading screens and hi-score
tables in your games. So it's a good idea to make full use of them in
your progs.

                      TEXT (print graphical text)

TEXT x,y,t$

TEXT prints a line of text in t$ at graphical coordinates x,y. All
coordinates are measured relative to the characters baseline. This can
be determined using a special TEXT BASE function.

  Normally the baseline is positioned at the bottom of the character,
but some lowercase letters, such as "g", have a "tail" which extends
slightly below this point.

  As a default the type styles is set to eight-point Topaz. This may be
changed at any time using the SET FONT instruction. Try the following
program and notice how text can be placed at any pixel position on the
screen.

  Do
    Ink Rnd(15)+1,Rnd(15): Text Rnd(320)+1,Rnd(198)+1,"AMOS Basic"
  Loop

Al so notice how the colour of your text is set with INK rather than
the expected PEN and PAPER commands. This emphasizes the fact that the
TEXT command is basically a graphical instruction. So the control
sequences created by functions like CUP$ will be printed on the screen
instead of being correctly interpreted.

  There is no automatic line feed when the text reaches the end of the
current window. If you attempt to print something too large, the text
will be neatly clipped at the existing screen boundary. This can be
seen by the example below:

        Print String$("A",100):Text 0,100,String$("A",100)

           GET FONTS (create a list of all available fonts)

GET FONTS

The GET FONTS command creates an internal list of the all fonts
available from the current start-up disc. This list is essential to the
running of the SET FONT command, so you should always call GET FONTS at
least once before attempting to change the present font setting. The
contents of this list can be examined using the FONT$ function.

  WARNING! In order for GET FONTS to work, your current AMOS work disc
must always contain a copy of the standard LIBS folder along with its
contents. It's important to remember this fact when you are
distributing run-only or compiled programs because unless your discs
contain the required files, AMOS Basic will almost certainly crash!

           GET DISC FONTS (create a list of the disc fonts)

GET DISC FONTS

This command is identical to the previous GET FONTS instruction except
that it only searches for fonts on the disc. These fonts are contained
in the FONTS folder on your current boot-disc. If you want to use your
own fonts with AMOS basic, you'll need to copy these onto your normal
start-up disc. See the manual supplied with your Amiga for details of
this procedure.

            GET ROM FONTS (create a list of the rom fonts)

GET ROM FONTS produces a list of the fonts which are built into Amiga's
rom chips. At the present time there are just two of these fonts:
Eight-point Topaz and nine-point Topaz.

           =FONT$ (return details about the available fonts)

a$=FONT$(n)

Returns a string of 38 chars which describes font number n. This
function allows you to examine the font list created by a previous call
to one of the GET FONT commands.

  a$ contains a list of characters which hold the name and type of your
font. If a font does not exist, a$ will be loaded a null value "",
otherwise a string will be returned in the following format:

        Character     Description
           1-29       Font name
          30-33       Font height
          34-37       Identifier (set to either Disc or Rom)

See EXAMPLE 8.11!

                  SET FONT (choose a font for use by
                         the TEXT instruction)

SET FONT n

SET FONT changes the character set used by the TEXT command to font
number n. If the font is stored on the disc it will be automatically
loaded into your Amiga's memory. At the same time any previously sets
which are not in use will be removed. See EXAMPLE 8.12.

                       SET TEXT (set text style)

SET TEXT style

Allows you to change the style of a font. There are three styles to
choose from. "style" is a bit pattern in the following format:

        Bit  Effect
         0   Underline        By setting the appropriate bits in this
         1   Bold             pattern you can choose between a total
         2   Italic           of eight different text styles.

              =TEXT STYLE (return the current text style)

s=TEXT STYLE

This function returns the text style set from the SET TEXT command. The
result in "s" is a bit-map in the same format as that used by SET TEXT.

             =TEXT LENGTH (return the length of a section                           of graphic text)

w=TEXT LENGTH(t$)

The TEXT LENGTH function returns the width in pixels of the character
string a$ in the current font. The width of a character varies
depending on the size of your fonts. In addition, proportional fonts
such as Helvetica assign different widths for each individual
character.

               =TEXT BASE (return the current text base)

b=TEXT BASE

This function returns the position of the baseline of your font. The
baseline is the number of pixels between the top of a character and
point it will be printed on the screen. It's basically similar to the
hot spot of a sprite or bob.

Installing new fonts
If you wish to use your own fonts within AMOS Basic, you'll need to
install them onto a copy of your AMOS program disc. The basic procedure
is as follows:

 - Copy the required font files into the FONTS: directory of your boot-
   disc.
 - Further information can be found in the Extra's manual supplied with
   the Workbench 1.3 upgrade.

Troubleshooting
Problem:  GET FONTS seems to ignore any of the fonts on the current
          disc.
Solution: You've propably removed the original boot disc from your
          default drive. The Amiga's library routines expect to find
          the FONTS: directory on your start-up disc. This can be
          changed using the ASSIGN program in the UTILITIES folder.

Problem:  GET FONTS crahes the Amiga completely.
Solution: This problem can easily occur when you're creating programs
          in run-only or compiled format. GET FONTS requires the
          discfont.library in the LIBS folder in order to work.

Problem:  The SET FONT command returns a "fonts not examined" error.
Solution: Add a cal to GET FONTS to the start of your program.

9:MATHS FUNCTIONS

AMOS Basic includes a wide variety of the more commonly needed
mathematical functions. To conserve memory, AMOS uses the standard
Amiga library routines. The appropriate libraries will be loaded
automatically from your workbench disc the first time you call one of
these functions in a particular session. You should therefore ensure
that the current disc contains the file MATHTRANS.LIBRARY in the LIBS
folder.

Trigonometric functions
The trigonometric functions provide you with a useful array of
mathematical tools. These can be used for a variety of purposes, from
education to the creation of complex musical wabeforms.

                         DEGREE (use degrees)

DEGREE

Generally all angles are specified in radians. Since radians are rather
difficult to work with, it's possible to instruct AMOS to accept angles
in degrees. Once you've activated this feature any subsequent calls to
the trig functions will expect you to use degrees.

                      RADIAN (use radian measure)

RADIAN

THe RADIAN directive informs AMOS that all future angles are to be
entered using radians - this is the default.

                         =PI# (a constant PI)

a#=PI#

This function returns the number called PI which represents the result
of the division of the diameter of a circle by the circumference. PI is
used by most of the trigonometric functions to calculate angels. Note
that a # character is part of the token name! This is to avoid clashes
with your own variable names.

                              =SIN (sine)

s#=SIN(a)
s#=SIN(a#)

The SIN functions calculates the sine of the angle in n. Note that the
function always returns a floating point number.

                             =COS (cosine)
c#=COS(a[#])

The cosine function computes the cosine of an angle.

                            =TAN (tangent)

t#=TAN(a[#])

TAN generates the tangent of an angle.

                            =ACOS (arc cos)

c#=ACOS(n#)

The ACOS function takes a number between -1 and +1 and calculates the
angle which would be needed to generate this value with COS.

Note, we haven't provided you with ASIN, because it's not really
needed. It can be readily computed using the formula:

ASIN(X)=90-ACOS(X) : Rem Measured in degrees.
ASIN(X)=1.5708-ACOS(X) : Rem using radians

                          =ATAN (arc tangent)

t#=ATAN(n#)

ATAN returns the arctan of a number.

                        =HSIN (hyperbolic sine)

s#=HSIN(a[#])

HSIN computes the hyperbolic sine of angle a.

                       =HCOS (hyperbolic cosine)

c#=HCOS(a[#])

HCOS calculates the hyperbolic cosine of angle a.

                      =HTAN (hyperbolic tangent)

t#=HTAN(a[#])

HTAN returns the hyperbolic tangent of the angle a.

Standard mathematical functions

                           =LOG (logarithm)

r#=LOG(v[#])

LOG returns the logarithm in base 10 (log 10) of the expression in v#.

                      =EXP (exponential function)

r#=EXP(e#)

Calculates the exponential of e#. Example:

        Print Exp(1)
( result : 2.71828 )

                        =LN (natural logarithm)

r#=LN(l#)

LN computes the natural of naperian logarithm of l#.

                          =SQR (square root)

s#=SQR(v[#])

SQR calculates the square root of a number.



r=ABS(v[#])

ABS returns the absolute value of v, taking no account of its sign.

          =INT (convert floating point number to an integer)

i=INT(v#)

INT rounds a floating point number in v down to the nearest whole
integer.

                   =SGN (find the sign of a number)

s=SGN(v[#])

SGN returns a value of representing the sign of a number. There are
three possibilities.

        -1, if v is negative
         0, if v is zero
         1, if v is positive

Creating random sequences

                    =RND (random number generation)

RND generates a random integer between 0 and n inclusive. But if n is
less than zero, RND will return the last value it produced. This can be
very useful when debugging one of your programs.

              RANDOMIZE (set the seed of a random number)

RANDOMIZE seed

In practice, the numbers produced by the RND function are not really
random. They're computed internally using a complex mathematical
formula. The starting point for this calculation is taken from a number
known as the "seed". This seed is set to a standard value whenever you
load AMOS Basic into the computer. So the sequence of numbers generated
by RND will be exactly the same every time you run your game!

  The RANDOMIZE command allows you to set the seed value directly, so
that the numbers would really look like random every time.

  "seed" can be any value you wish. In order to generate a true random
numbers, you need some way of varying the seed from game to game. This
can be achieved using the TIMER instruction:

        Randomize Timer

TIMER is a Basic function which returns the amount of time which has
elapsed since your Amiga was switched on in the current session. All
timings are measured in units of a 50th of a second.

Manipulating numbers

                 =MAX (get the maximum of two values)

r=MAX(x,y)
r#=MAX(x#,y#)
r$=MAX(x$,y$)    MAX compares two expressions and returns the largest.
                 These expressions can be composed of numbers or
strings of characters, providing you don't try to mix different types
of expressions in one instruction.

        Print Max(10,4)
( result : 10 )

                =MIN (return the minimum of two values)

r=MIN(x,y)
r#=MIN(x#,y#)
r$=MIN(x$,y$)    This works the same way the =MAX does, except returns
                 the minimum value of compared numbers/strings.

               SWAP (swap the contents of two variables)

SWAP x,y
SWAP x#,y#
SWAP x$,y$       Swaps the data between any two variables of the same
                 type.

             FIX (set precision of floating point output)

FIX(n)

Changes the way your floating point numbers will be displayed on the
screen or printer. There are four possibilities.

If 0<n<16 then n denotes the number of figures to be output after
          the decimal point.
If n> 16  the printout will be proportional and any trailing zeros will
          be removed.
If n<0    Then all floating point numbers will be displayed in
          exponential format, and the absolute value of n will
          determine the number of digits after the decimal point.

If n=16   then the format will be returned to normal

        Fix(-4) : Print PI#

                DEF FN (create a user-defined function)

DEF FN name [(list)]=expression

The DEF FN command lets you create your own user-defined functions
within an AMOS Basic program. These can be used to compute commonly
needed values quickly and easily.

  "nane" is the name of the function you wish to define. "list" is a
set of variables separated by commas. Only the type of these variables
is significant. When you call your function, any variables you enter
with, will be automatically subsituted in the appropriate positions.

  "expression" can include any of the standard AMOS functions you wish.
Like all Basic expressions, it's limited just to a single line of prog.

                  FN (call a user-defined function)

FN name [(variable list)]

FN executes a function defined using DEF FN. Example:

        Def Fn Asin(X)=90-Acos(X)
        Degree
        Print Fn Asin(0.5)

10:SCREENS

The default screen
Whenever you run an AMOS Basic program a default screen is created as
screen zero. This forms a standard display which will be used for all
your normal drawing operations.

  The system defaults to a 16-colour screen with dimensions 320x200,
which can easily be altered from within your program. In addition, you
can also define up to seven further screen with power SCREEN OPEN
command.

Defining a screen

                      SCREEN OPEN (open a screen)

SCREEN OPEN n, w, h, nc, mode

SCREEN OPEN opens a screen, and reserves some memory it. The new screen
will now be used as the destination of all subsequent text and
graphical operations in your program.

  n is the identification number of the screen which is to be created
by this instruction. Possible values range from 0-7. If this screen
already exists, it will be totally replaced by your new definition.

  w holds the width of the screen in pixels. This is not limited to the
physical size of your display. It's perfectly lefal to define extra
large screens which may be manupulated using SCREEN OFFSET.

  h sets the height of your screen using the same system. Providing
you've enough memory, you can easily create screens which are much
larger than the visible screen area. These screens can be used in
conjunction with all the normal screen operations. So you can construct
your images off-screen, and scroll them into view with the SCREEN
OFFSET command.

  nc requests the number of colours required for the new screen. The
range of available colours varies from 2 to 64 (EHB). You can also
access the Amiga's special HAM mode with a value of 4096.

  "mode" allows you to choose the width of the individual points on the
screen. The Amiga supports screen widths of either 320 or 640 pixels.
You can select the required width by setting "mode" either LOWRES (0)
or HIRES ($8000).

  Here's a list of the possible screen options along with an indication
of the amount of memory they consume.

RESOLUTIONS

           2     320 x 200     8 k  Paper=0 Pen=1 Crsr=1, no flash
                 640 x 200    16 k     "      "      "      "
           4     320 x 200    16 k  Paper=1 Pen=2 Crsr=3, flash=3
                 640 x 200    32 k     "      "      "      "
           8     320 x 200    24 k     "      "      "      "
                 640 x 200    48 k     "      "      "      "
          16     320 x 200    32 k  This is a default screen 0
                 640 x 200    64 k
          32     320 x 200    40 k
          64     320 x 200    48 k  Extra Half-Bright mode (EHB)
         4096    320 x 200    48 k   Hold and Modify mode  (HAM)

Note that the memory sizes in the table only apply to a standard
screen. If you create taller of wider screens, the amount of memory is
consumed will obviously be considerable greater. Screen zero is
equivalent to:

        SCREEN OPEN 0,320,200,16,Lowres

                     SCREEN CLOSE (erase a screen)

SCREEN CLOSE n

SCREEN CLOSE deletes screen number n, and frees the memory for use.

                AUTO VIEW ON/OFF (control viewing mode)

AUTO VIEW OFF

WHen you open a screen using SCREEN OPEN the new screen is usualyy
displayed immediately. This can be very incovenient during the
initialisation stages of your programs.

  The AUTO VIEW OFF command provides you with full control over the
updating process. It turns off the automatic display system copletely.
You can then update the screen display at a convenient point in your
program using the VIEW instruction.

  AUTO VIEW ON  activates automatic screen updating.

                 DEFAULT (reset screen to its default)

DEFAULT

Closes all current open screens and restores the display back to its
original default setting. Example:

        Load Iff "AMOS_DATA:IFF/Amospic.IFF",0
        Wait Key
        Defaul

              VIEW (display the current screen settings)

VIEW

Displays any changes to the current screen settings at the next
vertical blank period. You only have to use this command when AUTOVIEW
is OFF.

Special screen modes
The colour of every point on the screen is determined by a value held
in one of the Amiga's 32 colour registers. Each register can be loaded
from a selection of 4096 different colours.

  Although 32 colours may seem rather a lot, particularly by ST
standards, it wasn't enough for the Amiga's designers. The easiest
solution would have been to increase the number of colour registers,
but this was quickly ruled out from reasons of cost.

  Instead, they invented two special graphics modes which cleveroly
exploited the existing registers to increase the maximum number of
colours on the screen.

  You've propably encountered these modes already. They're the infamous
Extra Half Bright and HAM modes. AMOS Basic provides full support for
both HAM and Half Bright modes. Here's a brief explanation.

Extra Half Bright mode (EHB)
Doubles the maximum colours on the screen to a grand total of 64. It
works by generating two colours for each of the 32 possible colour
registers.

  The first 32 colours load the colour value directly from one of the
registers. Each register contains a value between 0 and 4095 which sets
the precise shade of the final colour.

  The second group of colours, with numbers from 32 to 63, take one of
the previous registers and divide its contents by two. This produces 32
extra colours which are exactly half as bright as the normal colour
registers.

  In order to exploit EHB mode to the full, it's necessary to load the
32 registers with the brightest shades in your palette. This will
automatically generate a list of intermediate tones in colours 32-63.
Aside from t

Hold and Modigy mode (HAM)
The Amiga's hardware currently limits you to a maximum of six bit
planes per screen. This allows you to display up to 64 different
colours on the screen at once. If you wanted to display a photograph
though, you'd require hunderds or even thousands of colours on the
screen.

  This was the problem faced by Jay Miner when he was designing the
Amiga's display system. His solution was to exploit a trick which has
been known by artists for centuries. If a professional aritst had to
take every conceivable colour on an assignment, he would be faced with
an impossible task. It's therefore common parctice to mix the exact
shade on the spot, out of a small set of basic colours. This provides
millions of potential shades, without the need to carry several large
lorry loads worth of paint. The same technique can also be applied to a
computer screen. Instead of specifying each colour individually, you
can take an existing colour and modify it slightly. This increases the
number of available colours tremendously, and forms the basis of the
Amiga's powerfl Hold And Modify mode.

  Each colour value on the Amiga is created from a mixture of the three
separate components. These determine the relative strength of the
primary colours Red, Green and Blue in the final colour. Possible
intenses range from 0 to 15.

  Ham mode splits the Amiga's colour values into four separate groups:

 * Colour registers 0-15: The first 16 colour take a value directly
                          from a colour register. These colours are
            treadted just like those on a standard 16 colour screen.

 * Red components   16-31: However, if a point is set to a colour
                           number in the range 16 to 31, the colour
            value is loaded from the pixel to its immediate left.
            The Red component of this colour is now replaced with a
            value from 0 to 15 which is calculated from the formula:

            Intensity=Colour index - 16

 * Green components 32-47: Similarly, a colour number from 32 to 47
                           takes the current shade, and changes the
            green component. The intensity of this component is set
            to a value of colour - 32.

 * Blue components  48-63: These colour numbers grab the colour value
                           from the point on the left of the current
            pixel, and load a new blue component from your colour
            number like so:

            Intensity = Colour Index - 48

The colour of a particular point therefore depends on the colours of
all the points to the left of it. This allows you to create smooth
gradiations of colour which are ideal for flesh tones. However, you
can't choose the colour of each point on the screen independently. In
practice, it takes a maximum of three pixles to shift from one colour
to another.

  When the Amiga was first released, Ham initially was regarded as
little more than curiosity. Nowadays, the situation is very different,
with the advent of excellent Ham graphics packages such as Photon
Paint.

  AMOS allows you to perform the full range text and graphics
operations directly on to a Ham screen. EXAMPLE 10.1 provides you with
a simple example of how you can generate an entire screen in just a few
lines of Basic code.

  Another point to consider, is that Ham screens are manipulated using
the normal SCREEN DISPLAY and SCREEN OFFSET commands. Here are some
simple guidelines to their use:

 * The first point in each horizontal line should be set to a colour
   number from 0 to 15. This will serve as the starting colour for all
   the shades on the current line.

 * Don't attempt to subject your Ham screens to horizontal scrolling.
   If you try to scroll one of these screens, you'll get colour fringes
   at the sides of your picture. These are generated by the changes in
   the starting colours for each line. There are no such restrictions
   to vertical scrolling.

 * Fringing effects can also be produced by SCREEN COPY. The solution
   is to ensure that the border of your zone is drawn using a colour
   from 0 to 15. This will ensure that your Ham screens will be redrawn
   at their new position with their original colours.

Loading a screen

              LOAD IFF (load an IFF screen from the disc)

LOAD IFF "filename"[,screen]

Loads an IFF format picture from the disc. "Screen" indicates the
number of the screen which is to be loaded with your picture. This
screen will be opened automatically for your use, if it didn't exist.
Anything already inside your screen will be totally erased.

  To load the picture into the present screen, omit the "screen"
parameter altogether.

  Example:

  Load Iff "AMOS_DATA:IFF/AMOSPIC.IFF",1

Saving a screen

                     SAVE IFF (save an IFF scree)

SAVE IFF "filename"[,compression]

Saves the current screen as an IFF picture file on the disc.
"compression" is a flag which allows you to choose whether your file
will be compacted before it's saved. A value of one specifies that the
standard file compressiong system is to be employed and zero saves the
picture as it stands. As a default all AMOS screens are compressed.

  SAVE IFF automatically appends a small IFF "chunck" to your picture
file. This stores the present screen settings including SCREEN DISPLAY,
SCREEN OFFSET and SCREEN HIDE/SHOW. When you load this file back into
AMOS Basic it will be returned to exactly its original condition. This
extra IFF data will be completely ignored by external graphics packages
such as DPaint 3.

  Note that it's possible to save double buffered or dual playfield
screens with this command.

Moving a screen

                  SCREEN DISPLAY (position a screen)

SCREEN DISPLAY n [, x, y, w, h]

Once you have defined your screen with SCREEN OPEN, you'll need to
position it on your screen. Unlike most other computers, the Amiga is
capable of displaying a picture anywhere you like on the TV screen.
This can be easily exploited to produce amazing "bouncing" screen
effects. With AMOS Basic, it's even possible to perform these
animations using interrupts (see AMAL).

  Another aplication is to overlay several screens alongside each
other. This allows you to create your display out of a combination of
different screen modes.

  "n" indicates the number of the screen to be positioned. "x" and "y"
specify the location of the screen in hardware coordinates.

  The x coordinates of a screen can range from 0 to 448 and are
automatically rounded down to the nearest 16-pixel boundary. Only the
positions between 112 and 448 actually visible on your TV though, and
you are strongly advised to avoid using an x coordinate below 112.

  The y coordinates of your screen can range between 0 and 312. The
visible range will largely depend on your TV or monitor, but you'll
propably find that coordinates between 30 and 300 are satisfactory for
the majority of systems.

  At the time of writing, there appears to be a minor bug in the
Amiga's HAM mode. These pictures cannot be displayed with a Y
coordinate of exactly 256. So set your coordinates to intermediate
values such as 255 or 257 instead. We're not sure if it's a hardware or
software fault yet but it won't restrict you by any means.

  "w" holds the width of your screen in pixels. If this is different
from the original setting, only a part of your image will be shown,
starting from the top left corner of the display. Like the x
coordinates, the screen width will be rounded to the nearest 16 pixel
boundary.

  Similarly, "h" sets the apparent height of the screen. Changing this
value will reduce the depth of your image.

  Generally SCREEN OPEN will automatically select the display position
for you using a standard setting in the AMOS configuration file. If a
screen is larger than the display then AMOS sets the screen into
overscan.

  SCREEN DISPLAY provides you with a simple way of changing these
values from the default. Any of the parameters x,y,h and w may be
omitted as appropriate. The unused values will be automatically
assigned to the default settings, and should be separated by commas.

        Screen Display 0,112,45,, : Rem position the screen at 112,45.

When you are positioning your screens, try to ensure that the screen
starts at the left of the display and ends towards the right. This is
essential if the Amiga's hardware is to interpret your screen
correctly. In practice, you may need to experiment a little to get the
precise effect you want. Fortunately, the worst that can happen is that
you'll get a silly looking display. The Amiga won't crash if you make a
mistake. here are some guidelines to help you along:

 * Only a single screen can be displayed on each horizontal line.
   However, you can safely place several screens on top of each other.
   All will be well, providing only one of the screens visible.

 * There will always be a one pixel thick "dead zone" between each pair
   of screens. This is generated by the copper list and is completely
   unavoidable. The dead zone will be noticeable whenever you move a
   sprite between the screens. As an example, try moving the mouse
   pointer from the editor window to the menu line. You should see a
   small black line through your mouse pointer at the border between
   the two screens.

                       SCREEN OFFSET (hardware scrolling)

SCREEN OFFSET n,x,y

The Amiga's display is not just limited to the visible dimensios of
your TV screen. There's absolutely nothing stopping you from generating
images which are much larger than the actual screen. It's obviously not
possible to display such pictures in their entirety, but you can easily
view a section of your image using the SCREEN OFFSET command.

  "n" is the number of the screen to be displayed. x,y measure the
offset from the top left hand corner of the screen to the starting
point for your display. x and y are specified in units of a single
pixel, so there's nothing stopping you from generating some
delightfully smooth scrolls.

  You can also use negative offsets with this instruction, allowing you
to display any part of the Amiga's memory on the screen. See
EXAMPLE 10.2 for a full demonstration of this command.

Screen control commands

                     SCREEN CLONE (clone a screen)

SCREEN CLONE n

The SCREEN CLONE command assigns a second version of the current screen
to screen number n. This clone uses exactly the same memory area as the
original screen.

  Normally, the cloned screen is displayed at the same place as its
parent. However it can be manupulated separately using any of the
normal screen operations such as SCREEN DISPLAY and SCREEN OFFSET.

  Since there's only a *single* copy of the original screen data in
memory, you can't access a clone with the SCREEN command. You'll get an
"illegal screen parameter" error if you rty. Another point to consider
is that any colour flash sequences you've set up on the original screen
will NOT be copied during the cloning operation. See EXAMPLE 10.3.
Notice the use of the WAIT VBL command. This ensures that the clone is
repositioned off-screen and keeps the movements running smoothly.

  If you experiment with SCREEN CLONE, you'll quickly find that there's
a real limit to the amount of movement you can perform without spoiling
the effect completely. Even something as trivial as an extra
calculation to your movement routine can often introduce an
unacceptable delay into your animations.

  The screen display can also be adjusted directrly from the AMAL
animation language. This is capable of animating large numbers of
screens smoothly and easily. See EXAMPLE 10.4 for a demonstration.

                  DUAL PLAYFIELD (combine two screens
                         into dual playfield)

DUAL PLAYFIELD screen1, screen2

The Amiga's dual playfield mode allows you to display two complete
screens simultaneously at the same x and y coordinates. It's almost as
if you'd drawn eaxh screen on cellophane and overlayed them on top of
each other. Each screen can be manipulated totally independently. You
can exploit this to produce a smooth parallax effect which is ideal for
screen scrolling games such as Silkworm.

  The two components of a dual playfield are treated just like any
other AMOS screen and can be written to in the normal way. They can
even be animated within AMAL or double buffered.

  "screen1" and "screen2" refer to screens which have been previously
defined with the SCREEN OPEN command. Only certain screen combinations
are acceptable. Both screens MUST use the same resolution, as it's
illegal to use hires(meaning actually MedRes) and lowres in the same
playfield.

Here is a list of the possibilities

        Screen 1    Screen 2    Notes

        #of colours #of colours
            2           2
            4           2
            4           4
            8           4       LowRes only
            8           8       LowRes only

Although the colour ranges are predefined, the sizes of the two screens
can be completely different. By creating a background screen which is
larger than the foreground you can create a delightfully realistic
parallax effect.

  The colours of these screens are all taken from the palette of
screen1 with colour zero being treated as transparent.

        Screen  Colour indexes (from screen 1)
          1       0 - 7
          2       8 - 15

When you are drawing to the second screen, AMOS Basic will
automatically convert your colour index to the appropriate number
before using it. So INK 2 will use colour nine from the first palette.

  This conversion process does not apply to the assignment statements
such as COLOUR or PALETTE. It's important to remember this when you are
changing the colour settings, otherwise your new colours will not be
reflected on the actual screen. Always make "screen1" the current
screen before changing your colour assignments.

There are a couple of important opints which you must be aware of
before setting up a dual playfield screen:

   * The screen offsets for both screens must never be set to zero.
   * If you set a dual playfield screen up and then want to position
      it with SCREEN OFFSET be sure to specify dual screen 1 not the
      second.

DUAL PLAYFIELD is an extremely powerful instruction. A full
demostration can be found in EXAMPLE 10.5.

        DUAL PRIORITY (choose order of dual playfield screens)

DUAL PRIORITY screen1,screen2

The first screen of a dual playfield is normally displayed directrly
over the second. The DUAL PRIORITY command allows you to change this
order around so that screen2 appears in front if screen1

  WARNING! This instruction only changes the order of the display. It
has *NO* effect on the screen organization. The first screen in the
dual playfield list should therefore still be used for all colour
assignments and with SCREEN DISPLAY.

                      SCREEN (set current screen)

SCREEN n

The SCREEN command allows you to direct all graphical and text
operations to screen number n.

                  =SCREEN (get the current screen #)

s=SCREEN

Returns the number of the currently active screen.

          SCREEN TO FRONT (moves screen to front of display)

SCREEN TO FRONT [s]

This instruction moves screen "s" to the front of the TV display. If
the parameter is omitted, then the current screen will be used instead.

Note: if the AUTOVIEW system has been turned off, you'll need to call
the VIEW command before the effect will be visible on the screen.

            SCREEN TO BACK (move screen to back of display)

SCREEN TO BACK [n]

SCREEN TO BACK moves a screen to the background of your display. If
there is another screen at the same coordinate this will now be
displayed in front of the selected screen.

                SCREEN HIDE (temporarily hide a screen)

SCREEN HIDE [n]

Removes a selected screen from view copletely. This screen can be
redisplayed using a call to SCREEN SHOW. If n is omitted, this
instruction will hide the current screen.

                    SCREEN SHOW (restore a screen)

SCREEN SHOW [n]

Screen SHOW returns a screen onto the display after it has been hidden
with the SCREEN HIDE command.

               =SCREEN HEIGHT (return height of screen)

h=SCREEN HEIGHT [n]

Returns the height of an AMOS screen. If you don't include the
parameter n, the height will be returned for the current screen.

              =SCREEN WIDTH (return the  width of screen)

w=SCREEN WIDTH [n]

SCREEN WIDTH retrieves the width of either the current screen or screen
number n. Example:

        Print Screen Width

             =SCREEN COLOUR (return the number of colours)

c=SCREEN COLOUR

Returns the maximum numbers of colours in the currently active screen.

         =SCIN (returns screen number at a selected position)

s=SCIN(x,y)

Returns the number of screen which is underneath the *hardware*
coordinates x,y. If this screen does not exist, then s will be loaded
with a negative value (null).

  SCIN is normally used in conjuction with the X MOUSE and Y MOUSE
functions to check whether the mouse cursor has entered a particular
screen. Example:

        Print Scin(X Mouse, Y Mouse)

Defining the screen colours

          DEFAULT PALETTE (load screen with standard palette)

DEFAULT PALETTE c1,c2,c3,,,c6,,-> up to 32 colours

This command simplifies the process of opening many screens with the
same palette. It defines a list of colours which will be used for all
subsequent screens which you create with the SCREEN OPEN instruction.
As usual, the allowable colour values range from $000 to $FFF.

              GET PALETTE (set the palette from a screen)

GET PALETTE n [,mask]

The GET PALETTE instruction copies the colours from screen n and loads
them into the current screen. This can be very useful when you're
moving information from one screen to another with SCREEN COPY, as it's
usually vital that both the source and destination screens share the
same colour settings.

  The optional "mask" parameter allows you to load just a selection of
the colours. See GET SPRITE PALETTE for full details of mask.

Clearing the screen

                        CLS (clear the screen)

CLS erases all or part of the current screen. There are three possible
formats of this command:

        CLS

Clears the current screen by filling it with colour zero and clears any
windows which may have been set up.

        CLS col

Fills your screen with colour col.

        CLS col,x1,y1 to x2,y2

Replaces the rectangular region at coordinates x1,y1,x2,y2 with a block
of colour col. Col can take any value from 0 to the max. number of
available colours. x1,y1,x2,y2 hold the coordinates for top left and
bottom right corners of the area to be cleared by this command.
Example:

        Cls : Circle 100,09,09 : Cls 1,50,50 To 150,150

Manipulating the contents of a screen

               SCREEN COPY (copy sections of the screen)

SCREEN COPY scr1 TO scr2

SCREEN COPY scr1,x1,y1,x2,y2 TO scr2,x3,y3 [,mode]

SCREEN COPY makes it possible to copy large sections of a screen from
one place to another at amazing speed.

  "scr1" holds the screen used as the source of your image. This can be
either a standard screen number or the number of a logical or physical
screen generated using the LOGIC and PHYSIC commands.

  "scr2" selects an optional destination screen into which this data
will be copied. If it's omitted, the area will be copied into the
current screen.

  x1,y1 and x2,y2 hold the dimensios of a rectangular source area, and
x3,y3 contain the coordinates of the destination. There are no
limitions to these coordinates whatsoever. Any parts of your image
which lie outside the current screen area will be automatically clipped
as appropriate.

  The optional "mode" parameter chooses which of the 255 possible
blitter modes will be used for your copying operation. These modes
determine how your source and destination areas will be combined
together on the screen. The mode is set using a bit-pattern in the
following format:

        Mode Bit        Source Bit      Destination Bit
           4                0                  0
           5                0                  1
           6                1                  0
           7                1                  1

Note that the bottom four bits in the pattern are not used by this
instruction and should always be set to zero.

  Each bit in "mode" represents a single combination of bits in the
source and destination areas. If a mode bit is set to one, then the
associated bit on the screen will also be loaded with a one, otherwise
the result will be zero.

  In order to select the correct drawing mode for you application, you
simply decide which combinations should result in a one and set the
appropriate bits in the "mode" parameter accordingly.

  Supposing you only wanted to set a bit on the screen if both the
source and destination bits were the same. You would look the table for
the points where your requirement was satisfied. This would produce the
following vaue for "mode":

        %10010000

If you're not familiar with binary notation, you may find this command
a little opaque. Rather than boring you silly with an explanation of
binay we'll now provide you with a detailed list of the more common
requirements along with the associated bit-maps.

        Mode    Effect                                  Bit-pattern
        REPLACE Replaces the destination with a direct   %11000000
                copy of the source image (default).
        INVERT  Replaces the destination image by a      %00110000
                reversed copy of the source image.
        AND     Combines the source and destination      %10000000
                with a logical AND operation.
        OR      OR's the source with the destination     %11100000
                image.
        XOR     Combines the source and destination      %01100000
                area with an Exclusive OR.

Technically-minded users should note that SCREEN COPY combines the
source and destination using blitter areas B and C and that blitter
area A is not used by the system at all.

Scrolling the screen

                   DEF SCROLL (define a scroll zone)

DEF SCROLL n,x1,y1 to x2,y2,dx,dy

Allows you to define up to 16 different scrolling zones. Each of these
zones can be associated with a specific scrolling operation which is
determined by the variables dx and dy.

  n holds the number of the zone and can range from 1 to 16. x1,y1
refer to the coordinates of the top left-hand corner of the area to be
scrolled and x2,y2 to the point diagonally opposite.

  dx signifies the number of pixels the zone will be shifted to the
right in each operation. Negative numbers indicate that the scrolling
will be from right to left, and positive numbers from left to right.

  Similarly, dy holds the number of pixels the zone will be advanced up
or down during the scroll. In this case negative values of dy are used
to indicate an upward movement and positive values a downward motion.

                      SCROLL (scroll the screen)

SCROLL n

The SCROLL command scrolls the screen using the settings you have
specified with the DEF SCROLL instruction. n refers to the number of
the zone you wish to scroll.

        Load Iff "AMOS_DATA:IFF/Frog_Leap.IFF",2
        Def Scroll 1,0,0, to 320,200,1,0
        Do
          Scroll 1
        Loop

Larger examples can be found in EXAMPLE 10.7 and EXAMPLE 10.8. The
variable s holds the number of points the picture will be moved during
each SCROLL. Note the use of screen switching to improve the quality of
the motion.

Screen switching
In order to produce the smooth movement effects found in a computer
game, it's necessery to complete all the drawing operations within a
time span of no more than a 15th of a second. This represents a real
challenge for the fastest computer, and it's often impossible to
achieve even on the Amiga. If the animation is complex, your graphics
will therefore tend to flicker annoyingly as they are being drawn.

  Fortunately, there's a solution at hand which has been succesfully
exploited in the vast majority of modern arcade games. This *screen
switching* technique can easily generate flicker-free screen animation
using just a fraction of Amiga's computing power.

  The basic idea is extremely simple. Instead of constructing your
images on the actual screen, you perform all your drawing operations on
a separate logical screen, which is copletely invisible to the user.
This is distinct from the *physical screen* which is currently being
displayed on your TV. Once the graphics have been completed, you can
then swap the logical and physical screen to produce a smooth
transition between the two screen images. The old physical screen now
becomes the new logical screen, and is used to construct the next
picture in your sequence.

  At fist glance, this process looks pretty complicated, but it's all
performed automatically by the AMOS Basic DOUBLE BUFFER command. This
forces all drawing operations to be performed directly on the logical
screen without affecting the current display. All you need to do within
your program is to synchronise your drawing operations with the screen
switches. This can be achieved with the help of SCREEN SWAP
instruction.

          SCREEN SWAP (swap the logical and physical screens)

SCREEN SWAP [n]

SCREEN SWAP swaps the physical and logical screens. This enables you to
instananeously switch the physical display between the two screens.

  If you're using DOUBLE BUFFER, these screens will have been created
for you already. However, you will need to switch off the automatic
screen switching system with BOB UPDATE OFF, as otherwise the screens
will be swapped 50 times a second, and will interfere with your own
drawing operations. It's also necessary to kill the autoback feature
with AUTOBACK OFF. This normally copies your graphical operatoins onto
both physical and logical screens. It's useful when you wish to combine
simple graphics with moving bobs, but it destroys the effect of your
screen switching operations totally.

  As an illustration of the power of this command, have a look at the
programs EXAMPLE 10.9 and EXAMPLE 10.10.

                =LOGBASE (return the address of part of
                      part of the logical screen)

address=LOGBASE(plane)

The LOGBASE function is aimed at expert programmers who wish to access
the Amiga's screen memory directly. "plane" referes one of the six
possible bit-planes which make up the current screen. After LOGBASE has
been called, "address" will contain either the address of the required
bit-plane, or zero if it doesn't exist.

                   =PHYSBASE (return the address of
                          the current screen)

address=PHYBASE

PHYBASE returns the address in memory of bit-plane number "plane" for
the current screen. If this plane does not exist, then a value of zero
will be returned by this function. Example:

        Loke Phybase(0),0 : Rem pokes a thin line directly onto the
                                screen.

                     =PHYSIC (return identifier of
                         the physical screen)
=PHYSIC
=PHYSIC(s)

The PHYSIC function returns an identification number for the current
physical screen. This number allows you to directly access the physical
image which is being displayed by the double buffering system.

  The result of this function can be substituted for the screen number
in the ZOOM, APPEAR and SCREEN COPY commands.

  "s" is the number of an AMOS screen. If it's omitted, then the
present screen will be used instead. Don NOT confuse with the LOGBASE
function.

                     =LOGIC (return identifier of
                          the logical screen)
=LOGIC
=LOGIC(s)

Returns an identification number of a logical screen. This can be used
in conjunction with the SCREEN COPY, APPEAR and ZOOM commands to change
your image off-screen, without affecting the current display.

Screen synchronisation
Like most home computers the AMIGA uses a memory-mapped display. This
is a technical term for a concept you are almost certainly already
familiar with. Put simply, a memory-mapped display is one which uses
special hardware to convert en image stored in memory into a signal
which can be displayed to your TV screen. Whenever AMOS Basic accesses
the scren it does so through the medium of this screen memory.

  The screen display is updated by the hardware every 50th of a second.
Once a screen has been drawn, the electron beam turns off and returns
to the top left of the screen. This process is called the vertical
blank period VBL. At the same time, AMOS Basic performs a number of
important tasks, such as moving the sprites and switching the physical
screen address if it has changed. The actions of instructions such as
ANIM or SCREEN SWAP will therefore only be fully completed when the
screen is redrawn.

  Since a 50th of a second is a quite long time for AMOS Basic, this
can lead to a serious lack of coordination between your program and the
screen, which is especially noticeable in tight program loops. The best
way of avoiding this is difficulty, is to wait until the screen has
been updated before you execute the next Basic command.

                 WAIT VBL (wait for a vertical blank)

The WAIT WBL instruction halts the AMIGA until ne next vertical blank
period. It is commonly used after either a PUT BOB insturction or a
SCREEN SWAP

Special effects

                  APPEAR (fade between two pictures)

APPEAR source TO destination, effect [,pixels]

The APPEAR command enables you to produce fancy fades between the
"source" and "destination" screens. Source and destination are simply
the numbers of screens you've previously opened using SCREEN OPEN. You
can also substitute the LOGIC and PHYSIC functions in these positions
if required.

  "effect" determines the type of fade which will be produced by this
insturction. The size of this parameter can vary from 1 to the number
of pixels in you current screen.

  "pixels" specifies the number of points which are to affected.
Normally this value is set to the TOTAL screen area, but you can reduce
it to fade only a part of the screen. All screens are drawn in strict
order from the top of the screen to the bottom.

  The appearance of your fades will naturally vary depending on the
screen mode you are using. A program is provided in EXAMPLE 10.11  to
allow you to experiment with the various possibilities.



                    FADE (blend one or more colours
                         to new colour values)

FADE speed [,colour list]
FADE speed TO screen [,mask]

The FADE command allows you to smoothly change the entire palette from
one set of colours to another. This can be used to generate
professional-looking fade effects for your loading screens.

  The standard version of the instruction takes the current palette,
and slowly dissolves the screen colours to zero. Each colour value is
successively reduced by one until they reach zero. Example:

        Fade 15 : Wait 225

  "speed" is the number of vertical blank periods that must occur
before the next colour change is performed.

  Since the fadig effects are executed using interrupts, it's best to
wait until the operation has completely finished before proceeding to
the nexy Basic instruction. The time taken for the fade WAIT can be
calculated by the formula:

        wait value = fade speed * 15

Fade can be extended to generate a new palette directly from a list of
colour values.

        Fade 15,$100,$200,$200,$300

Any number of colours can be specified in this instruction, up to the
maximum allowed in the current graphics mode. Like most AMOS commands,
it's possible to omit selected parameters completely. These colours
will be totally unaffected fy the FADE command.

        Fade 15,,$100,$800,$F00

The most powerful form of FADE smoothly transforms the colours from the
current screen into a palette taken from an existing screen.

        Fade speed TO s [,mask]

The present colours are slowly converted into the palette of screen s.
It's also possible to load the palette from the sprite bank using the
same technique. Simply use a negative value for the screen number s.

  "mask" is a bit-pattern which specifies which colours should be
loaded. Each colour is associated with a single bit in this pattern
numbered from 0 to 15. If a bit is set to 1, then the relevant colour
will be changed. See EXAMPLE 10.12.

                 FLASH (set flashing colour sequence)

This command gives you the ability to periodically change the colour
assigned to any colour index. It does this with an interrupt similar to
that used by the sprite and the music instructions. The format of the
flash instruction is:

        FLASH index,"(colour,delay)(colour,delay)(colour,delay)..."

  "index" is the number of the colour which is to be animated. Delay is
set in units of a 50th of a second.

  Colour is stored in the standard RGB format (See COLOUR) for mode
details. The action of FLASH is to take each new colour from the list
in turn, and then load it into the index for a length of time
specified by the delay. When the end of this list is reached, the
entire sequence of colours is repeated from the start. Note that you
are only allows to use a max. of 16 colour changes in any one FLASH
instruction. Here is a small example:

        Flash 1,"(007,10)(000,10)"

This alternates colour number 1 between blue and black every 10/50th of
a second.

        FLASH OFF

Turns off the flashing. Note that on start-up, colour number 3 is
automatically assigned a flash sequence for use by the cursor. It's a
good idea to turn this off before loading any pictures from the disc.

                      SHIFT UP (colour rotation)

SHIFT UP delay,first,last,flag

The SHIFT UP command rotates the values held in the colour registers
from the "first" to "last". The "first" colour in the list is copied
into the second, and the second into the third, and so on, until the
"last" colour in the series is reached.

  Each AMOS screen can have its own unique set of colour animations.
Colour shifts can be used to create amazing hyperspace sequences
similar to those found in Captain Blood and Elite. Since these
animations are performed using interrupts, they can be executed while
your program is running, without affecting it in the slightest.

  "delay" is the time interval between each stage of the rotation,
measured in 50ths of a second.

  "flag" controls the type of rotation. If it's ste to one, the last
colour index in the list will be copied into the first, and the first
to the last. So the colours will rotate continuously on the screen.
When "flag" is set to zero, the contents of the first and last indexes
will be discarded, and the region between first and last will be
replaced by a copy of the first colour in the list. For example:

        SHIFT UP 100,1,15,1

        SHIFT UP 10,1,15,0

                     SHIFT DOWN (colour rotation)

This is similar to the SHIFT UP, except it rotates the colours in the
opposite direction.

         SHIFT OFF (stops col.rotation for the current screen)

SHIFT OFF

Immediately terminates all colour rotations produced by the SHIFT UP or
SHIFT DOWN instructions

                 SET RAINBOW (define a rainbow effect)

Defines an attractive rainbow effect which can be subsequently
displayed using the RAINBOW command. It works by changing the shade of
a colour according to a series of simple rules.

  "n" is the number of your rainbow. Possible values range from 0 to 3.
"colour" is a colour index which will be changed by the instruction.
This colour can be assigned a different value for each horizonal sreen
line (or scan line). Note that only colours 0-15 can be manipulated
using this system.

  "length" sets the size of table to store your colours. There's one
entry in this table for each colour value on the screen. The size of
this table can range from 16 to 54400. If "length" is less than the
physical height of your rainbow, then the colour pattern will be
repeated several times on the screen.

  The r$,g$,b$ command strings, progressibely change the intensities of
the red, green and blue components of your final colour. These values
are loaded into a special colour table. Each colour in the table
determines the appearance of a single horizontal scan line on the
screen.

  At the start of the rainbow, all the components in your colour are
initially loaded with a value of zero. This will be changed according
to the information held in the colour table.

  Any command string may be omitted if required, but you'll still have
to include the quotes and the commas in their expected positions.

  Each string can contain a whole list of commands. These will be
cycled continually to produce the final rainbow pattern. The format is:

        (n,step,count)

"n" sets the number of lintes to be assigned to a specific colour value
in the rainbow. Increasing this number will change the height of each
individual rainbow line.

  "step" holds a number to be added to the component. This number will
be used to generate the colour of the succeeding line on the screen. A
positive step will increase the intensity of colour component, and a
negative value will reduce it.

  Whenever a particular component exceeds the maximum of 15, a new
value will be calculated from the formula:

        new component = old component Mod 15

"count" is the number of times the current operation is to be repeated.
The best way to demonstrate this command is with an example:

        Set Rainbow 0,1,64,"(8,2,8)","",""
        Rainbow 0,56,1,255
        Wait Key

This creates a new rainbow with number zero using colour index one. As
you can see, SET RAINBOW only defines your rainbow. In order to display
it on the screen you need to make use of the RAINBOW command.

  The rainbow effects first loads your colour with a value of zero.
Every four scan-lines, the red component will be automatically
incremented by two. So the contents of colour zero will progressively
change from $000 to $E00. WHen the component exceeds the maximum of 15,
its remainder will be calculated, and the colour will be returned to
its starting point (zero). The pattern will now be repeated down the
screen.

  By defining a separate pattern for eaxh of the red, green and blue
components of your colour, you can easily generate some starling
patterns on the screen. Since each rainbow only uses a single colour
index, there's nothing stopping you from creating the same effects
using just two colour screens. These are ideal from the backgrounds of
an arcade game, as they consume very little memory. Example:

        Screen Open 0,320,256,2,Lowres
        Set Rainbow 0,1,128,"8,1,8)","(8,1,8)",""
        Rainbow 0,1,30,128
        Colour 1,0 : Curs Off : Cls 1 : Flash Off
        Locate 0,2 : Centre "Amos Basic" : Wait Key

For further demonstration of the superb effects that can be achieved
with this instruction load up EXAMPLE 10.13.

  Rainbows can also be animated using a powerful interrupt system. See
the section on AMAL for more details.

                    RAINBOW (create a rainbow effect)

RAINBOW n,base,y,h

Displays rainbow number n on the screen. If AUTOVIEW is set to OFF, the
rainbow will only appear when you next call the VIEW command.

  "base" is an offset in the first colour in the table you created with
SET RAINBOW. Changing this value will cycle the rainbow on the screen.

  y holds the vertical position of the rainbow in hardware coordinates.
The minimum calue for this coordinate is 40. If you attempt to use a
coordinate below this point, the rainbow will be displayed from line 40
onwards.

  h sets the height of your rainbow scan lines.

  Rainbows are totally compatible with the AMOS system including bobs
and sprits. However, don't attempt to rainbow a colour which is
currently being changed using the FLASH or SHIFT instructions, as this
will lead to unpredictable screen effects.

  Note that only a single rainbow effect can be displayed on a
particular scan line, even if they use different colours on the screen.

  Normally the rainbow with the highest screen position will be
displayed first. But if several rainbows start from the same scan line,
then the rainbow with the lowest identification number will be drawn in
front of the others.

                    =RAIN (change the colour of an
                       individual rainbow line)
RAIN(n,line)=c
c=RAIN(n,line)

This is the most powerful of all the rainbow creation commands, as it
allows to change the colour of an individual rainbow line to any value
you like.

  n is the number of the rainbow you wish to access. "line" is the
individual scan line to be changed. Example:

        Curs Off : Centre "Securitate Stinks!"
        Set Rainbow 1,1,4097,"","",""
        For Y=0 To 4095
          Rain(1,Y)=Y
        Next Y
        For C=0 to 4095-255
          Rainbow 1,C,40,255
        Next C
        Wait Key

                ZOOM (magnify a section of the screen)

ZOOM source,x1,y1,x2,y2 TO dest,x3,y3,x4,y4

ZOOM is a simple instruction which allows you to change the size of any
rectangular region of the screen.

  "source" is the number of a screen from which your picture will be
taken. You can also use the LOGIC function to grab your image from the
appropriate logical screen. The rectangular area to be affected by this
instruction is entered using the coordinates x1,y1,x2,y2. "dest" holds
the destination screen for your image. Like the source, it can be
either a screen number, or a logical screen specified using LOGIC.

  The dimensios of this screen are taken from the cordinates x3,y3 and
x4,y4. These hold the dimensios of the rectangle into which the screen
segment will be compressed.

  The effect of this instruction depends on the relative sizes of the
source and destination rectanges. The source image is automatically
resized to fit exactly into the destination rectangle. So the same
instruction can be used to reduce or enlarge your images as required.

  See EXAMPLE 10.14 for a further demonstration.

Changing the copper list
The Amiga's co-processor (copper) provides total control over the
appearance of every line on your screen. This copper is a separate
processor with its own internal memory and unique set of instructions.
By programming the copper it's possible to freely generate a massive
variety of different screen effects. Normally the copper is managed
automatically by the AMOS system. Each of the available copper effects
can be performed directly from within AMOS Basic without the need to
indulge in complicated machine-level programming. In practive these
intructions will be more than sufficient for the vast majority of
applications.

  Obviously, no one can think of everything though. Expert programmers
may wish to access the copper directly to create their own special
screen modes.

  Be warned: The copper list is notoriously difficult to program, and
if you don't know precisely what you are doing, you'll almost certainly
crash your Amiga. Before embarking on your copper experiments for the
first time, you are therefore adviced to read one of the many reference
books on the subject. A good explanation can be found the "Amiga System
Programmers Guite" from Abacus.

             COPPER OFF (turn of the standard copper list)

COPPER OFF

Freezes the current AMOS copper list and turns off the screen display
copletely. You can now create your own display using a series of COP
MOVE and COP WAIT instructions.

  As a default, all user-defined copper lists are limited to a maximum
of 12k. On average, each copper instruction takes up two bytes. So
there's a space for around 6000 instructions. This may be increased if
required, using a special option from the CONFIG utility.

  Note that all copper instructions are written to a separate logical
list which is not displayed on the screen. This stops your program
corrupting the display while the copper list is being created. To
activate your new screen, you'll need to swap the physical and logical
lists around with the COP SWAP command.

  It's also important to generate your copper lists in strict order,
starting from the top left of your screen and progressing downward to
the bottom right. See EXAMPLE 10.15.

                  COPPER ON (restart the copper list)

COPPER ON

Restarts the AMOS copper list calculations and displays the current
AMOS screens.

                COP MOVE (write a MOVE instruction into
                       the logical copper list)

COP MOVE addr,value

Generates a MOVE instruction in the logical copper list.

  "addr" is an address of a 16 bit register to be changed. This must
lie within the normal copper DATA ZONE ($7F-$1BE). "value" is a
word-sized integer to be loaded into the requested register.

               COP MOVEL (write a long MOVE instruction
                           into copper list)

COP MOVEL addr,value

This is identical to the COP MOVE, except that "addr" now refers to a
32-bit copper register. "value" contains a long word intereger.

                  COP WAIT (copper WAIT instruction)

COP WAIT x,y [,x mask, y mask]

COP WAIT writes a WAIT instruction into your copper list. The copper
waits until the hardware coordinates x,y have been reached and returns
control to the main processor. Note that line 255 is automatically
managed by AMOS. So you don't have to worry about it at all.

  x mask and y mask are bit maps which allow you to wait until just a
certain combination of bits in the screen coordinates have been set. As
a default both masks are automatically assignet to $1FF.

                COP RESET (reset copper list pointers)

COP RESET

Restores the address used by the next copper instruction to the start
of the copper list.

                  =COP LOGIC (address of copper list)

addr=COP LOGIC

This function returns the absolute address in memory of the logical
copper list. This allows you to poke your COPPER instructions directly
into the buffer, possibly using assembly language.

Hints and tips
* Before creating a screen with a user defined copper list, you'll
  first need to allocate some memory for the appropriate bit-maps.
Although you can use RESERVE for this purpose, it's much easier to
define a dummy screen with the SCREEN OPEN command instead. The copper
registers can be loaded with the addresses of the required bit-maps
using the LOGBASE function.

  You'll now be able to access your screen using all the standard AMOS
drawing features. In order to reserve the correct amount of memory, set
the number of colours to the MAXIMUM used in the new screen. This may
be a little wasteful, but simplifies things enormously.

* It's perfectly acceptable to combine user-defined screens with AMOS
  bobs. If you're using double buffering though, you'll have to define
a separate copper list for both the logical and physical screens. This
may be achieved using the following procedure;

  1 Define your copper list for the first screen
  2 Swap the logical and physical copper lists with COP SWAP
  3 Swap the physical and logical screens with SCREEN SWAP
  4 Define your copper list for the second screen

This will ensure that your bobs will updated correctly on your new
screens. All the normal AMOS commands can be used including AMAL.

NOW LOAD PART THREE.....